homebridge-plugin-utils 1.34.0 → 2.0.0

package/dist/logclient/parser.js

@@ -0,0 +1,393 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * logclient/parser.ts: Pure incremental line splitter and per-line parser for Homebridge UI log text.
+ */
+// The ANSI escape-sequence regex. Matches CSI sequences (ESC `[` ... final byte) - which covers the SGR color sequences the log stream uses - so they can be stripped
+// when building the human-readable `message`. Compiled once at module scope since it runs on every parsed line on the parse hot path. Two character classes cover the
+// parameter bytes and then the intermediate bytes; the trailing class is the final byte that terminates the sequence.
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\[[0-9;?]*[ -/]*[@-~]/g;
+// The SGR (Select Graphic Rendition) foreground color codes homebridge-config-ui-x uses to convey severity, mapped to the corresponding {@link LogLevel}. The server
+// colors the MESSAGE portion of a line - not the whole line - by wrapping it in a single SGR sequence: 31 (red) error, 33 (yellow) warn, 90 (bright black) debug, 32
+// (green) success. An info line carries no message color, so the SGR code 39 is intentionally absent from this map (`readLevel` yields null for it); `parseLogLine` then
+// promotes a colored line with no severity color to "info", reserving null for a color-stripped line. The timestamp (37/white) and plugin (36/cyan) colors are
+// deliberately absent too - they prefix the message and must never be mistaken for severity. Frozen so the shared module-scope table cannot be mutated by a consumer.
+const SGR_LEVEL = Object.freeze({
+    "31": "error",
+    "32": "success",
+    "33": "warn",
+    "90": "debug"
+});
+// Match every SGR sequence in a string globally, capturing each one's numeric parameter. The severity color is read by scanning these from the point AFTER the
+// timestamp/plugin brackets (see {@link readLevel}), because the server colors the message body, not the line prefix; the timestamp's and plugin's own colors sit before
+// that point and are excluded by where the scan starts. The capture group is the parameter digits between `ESC[` and the terminating `m`.
+// eslint-disable-next-line no-control-regex
+const SGR_PATTERN = /\[([0-9;]*)m/g;
+// Match the conventional `[timestamp] [Plugin Name] ` prefix at the start of an ANSI-stripped line, capturing the timestamp and plugin text. Each bracketed field is
+// guaranteed present when the match succeeds: the timestamp is rendered white and the plugin name is rendered cyan; the remainder after the closing plugin bracket and
+// its trailing space is the message body. Both captures use a negated character class (`[^\]]*`) that cannot cross a `]`, so a message containing brackets is not
+// absorbed into the prefix.
+const BRACKET_PREFIX_PATTERN = /^\[([^\]]*)\] \[([^\]]*)\] /;
+// Recognize the Homebridge en-US default timestamp in both renderings the server emits: the 12-hour `M/D/YYYY, h:mm:ss AM` and the 24-hour `M/D/YYYY, HH:mm:ss` (meridiem
+// absent). One module-scope regex serves both - the meridiem group is optional - mirroring the other compiled-once patterns above. The capture groups are, in order:
+// month, day, four-digit year, hour, minute, second, and the optional AM/PM token.
+const LOG_TIMESTAMP_PATTERN = /^(\d{1,2})\/(\d{1,2})\/(\d{4}),\s+(\d{1,2}):(\d{2}):(\d{2})(?:\s*([AaPp][Mm]))?$/;
+// Capture the contents of the FIRST bracket at the very start of an ANSI-stripped line - used by {@link isLogLineStart} to test whether a line opens with a timestamp.
+// Only the first bracket is captured (the negated class cannot cross a `]`), because a genuine log entry begins with `[timestamp]` whether or not a `[plugin]` bracket
+// follows; the timestamp's parseability, not the presence of a second bracket, is what marks an entry start.
+const LOG_LINE_START_PATTERN = /^\[([^\]]*)\]/;
+// Strip every ANSI escape sequence from a string, leaving only the printable text. Used to derive the human-readable `message` from a raw line; the raw line itself
+// retains the escapes so a `--raw` consumer can reproduce the server's coloring.
+function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, "");
+}
+/**
+ * Cursor-based incremental line splitter for the log text stream.
+ *
+ * Feed each text chunk through {@link LogLineSplitter.consume} and iterate the raw lines it yields. The splitter carries the bytes of an incomplete trailing line across
+ * calls, so a line split across two chunks is reassembled transparently, and it recognizes all four newline conventions the PTY-driven stream mixes (`\r\n`, `\n\r`,
+ * `\r`, `\n`) as single line breaks. Crucially, a chunk that ends with a lone `\r` or `\n` holds that terminator in the carry rather than yielding immediately: the next
+ * chunk may begin with the matching second half of a `\n\r`/`\r\n` pair, and emitting eagerly would split one line break into two and inject a phantom blank line.
+ *
+ * The scan is a single integer cursor over the carried buffer; the buffer is rebuilt once per `consume` (the residual tail becomes the next carry), not once per line,
+ * so per-line work is a single `slice` of the line's content with no quadratic buffer churn. Because the splitter holds at most one partial line plus the current chunk,
+ * its memory is bounded by chunk size regardless of total stream length.
+ *
+ * The class is intentionally signal-free and event-free. Resource lifecycle and async consumption belong to the composing transport, exactly as `Mp4BoxParser` leaves
+ * those concerns to `Mp4SegmentAssembler`.
+ *
+ * @example
+ *
+ * ```ts
+ * const splitter = new LogLineSplitter();
+ *
+ * for(const line of splitter.consume(chunk)) {
+ *
+ *   handle(parseLogLine(line));
+ * }
+ * ```
+ *
+ * @category Log Client
+ */
+export class LogLineSplitter {
+    // The residual carry: the bytes of an incomplete trailing line (and any held lone terminator) from the previous call, prepended to the next chunk. Empty when the
+    // previous chunk ended exactly on a line break.
+    #carry = "";
+    /**
+     * Feed the splitter a text chunk and yield every complete raw line now available.
+     *
+     * Each yielded line is the content between line breaks with the terminator removed and ANSI escapes preserved. A line that is still incomplete (no terminator yet, or
+     * only a held lone terminator that may pair with the next chunk) is carried internally and surfaces on a later call once its break is unambiguous.
+     *
+     * @param chunk - A contiguous slice of log text from the transport.
+     *
+     * @returns An iterable of every complete raw line contained in (or completed by) this chunk, in stream order.
+     */
+    *consume(chunk) {
+        // Prepend the carry only when there is one, keeping the common "chunk completes its own lines and nothing is pending" path free of an empty-string concatenation.
+        const buffer = this.#carry.length > 0 ? this.#carry + chunk : chunk;
+        // `start` marks the beginning of the current line; `cursor` scans forward looking for terminators. We slice each line's content from `[start, breakStart)` and never
+        // rebuild `buffer` mid-loop - the residual tail is computed once at the end.
+        let start = 0;
+        let cursor = 0;
+        while (cursor < buffer.length) {
+            const character = buffer.charAt(cursor);
+            // Only `\r` and `\n` can start a line break; skip everything else with a single cursor advance.
+            if ((character !== "\r") && (character !== "\n")) {
+                cursor++;
+                continue;
+            }
+            // We found a terminator character. Determine whether it pairs with the following character to form a two-character break (`\r\n` or `\n\r`). The pair forms only
+            // when the partner is the OTHER terminator character - `\r\r` and `\n\n` are two separate breaks (two lines), not one.
+            const partner = character === "\r" ? "\n" : "\r";
+            const hasNext = (cursor + 1) < buffer.length;
+            // A lone terminator at the very end of the buffer is ambiguous: the next chunk might supply the partner that completes a two-character break. Hold the line (and
+            // this terminator) in the carry rather than yielding, so a `\n\r`/`\r\n` pair split across chunks is never seen as two breaks. We stop scanning here; the residual
+            // computed below preserves `[start, end)` including the held terminator.
+            if (!hasNext) {
+                break;
+            }
+            // The break is unambiguous now that we can see the next character. Yield the line content up to the terminator, then advance past either one or two characters
+            // depending on whether the partner immediately follows.
+            yield buffer.slice(start, cursor);
+            const isPair = buffer.charAt(cursor + 1) === partner;
+            cursor += isPair ? 2 : 1;
+            start = cursor;
+        }
+        // The residual is everything from the last unfinished line's start to the end of the buffer, including any held lone terminator. It becomes the carry for the next
+        // call. When `start` reached the buffer end exactly (the chunk ended on a complete break), the carry is empty.
+        this.#carry = buffer.slice(start);
+    }
+    /**
+     * Flush any buffered final line that never received a terminator.
+     *
+     * A log stream may end without a trailing newline, leaving the last line held in the carry. Call this once after the source has ended to surface that final line. It
+     * yields at most one line and clears the carry; calling it again yields nothing. A held lone terminator with no content (a trailing bare `\r`/`\n`) flushes as an
+     * empty final line, matching the convention that a terminator delimits a line that exists.
+     *
+     * @returns An iterable yielding the final unterminated line, or nothing if the carry is empty.
+     */
+    *flush() {
+        if (this.#carry.length === 0) {
+            return;
+        }
+        // Strip a single trailing lone terminator that was being held for possible pairing; at flush time no partner will arrive, so it delimits the end of the final line.
+        const trailing = this.#carry.replace(/[\r\n]$/, "");
+        this.#carry = "";
+        yield trailing;
+    }
+}
+/**
+ * Parse a single raw log line into a {@link LogRecord}.
+ *
+ * The `[timestamp] [Plugin Name] ` prefix is extracted from the ANSI-stripped text, and the remainder becomes the human-readable `message`. The severity level is read
+ * from the SGR color sequence that the server wraps around the MESSAGE - which means it appears AFTER the timestamp/plugin brackets, not at the start of the line: the
+ * timestamp (white) and plugin (cyan) carry their own colors, so reading the line's first color would always misclassify them as severity. We therefore scan for the
+ * severity color starting just past the plugin bracket. The original line is preserved verbatim in `raw`. A colored line that carries no severity color resolves to
+ * `level: "info"` (Homebridge's info convention), while a fully color-stripped line resolves to `level: null` because severity is genuinely unknown; a line with no
+ * bracketed prefix resolves to `timestamp: null` / `plugin: null`, a `message` equal to the full stripped line, and a level read from any severity color present
+ * anywhere in the (prefix-less) line.
+ *
+ * @param raw - A single raw log line (escapes intact, terminator already removed by {@link LogLineSplitter}).
+ *
+ * @returns The parsed {@link LogRecord}.
+ *
+ * @category Log Client
+ */
+export function parseLogLine(raw) {
+    // Strip ANSI to get the printable text, then peel the conventional `[timestamp] [Plugin Name] ` prefix. When the prefix is absent the whole stripped line is the
+    // message and both bracketed fields are null.
+    const stripped = stripAnsi(raw);
+    const match = BRACKET_PREFIX_PATTERN.exec(stripped);
+    if (match === null) {
+        // No bracketed prefix: this is a status or continuation line, not a formatted Homebridge log line, so the "uncolored = info" convention does not apply. The level is
+        // whatever severity color the line carries (read from the whole line, since there is no prefix to skip past), or null.
+        return { level: readLevel(raw, 0), message: stripped, plugin: null, raw, timestamp: null };
+    }
+    // A formatted log line. The severity SGR colors the message, so it sits after the timestamp/plugin brackets; we anchor the scan just past the plugin bracket's closing
+    // `]` in the raw line so the timestamp's (white) and plugin's (cyan) own colors are not read as severity. When the message has no severity color, the level depends
+    // on whether the line is colored at ALL: a colored line with an uncolored message is Homebridge's info convention ("info"), whereas a line with no ANSI whatsoever is
+    // color-stripped, leaving severity genuinely unknown (null). We read "is the line colored" for free from the strip already performed - stripping shortened the text if
+    // and only if the line carried ANSI - rather than scanning a second time.
+    const colored = stripped.length !== raw.length;
+    const level = readLevel(raw, messageColorStart(raw)) ?? (colored ? "info" : null);
+    // `match[1]` is the timestamp text and `match[2]` is the plugin text; each bracketed field is guaranteed present when the match succeeds. The message is the
+    // stripped text after the matched prefix.
+    return { level, message: stripped.slice(match[0].length), plugin: match[2] ?? null, raw, timestamp: match[1] ?? null };
+}
+// Locate, in the RAW (still-escaped) line, the index just past the second `]` - the plugin bracket's close - so the severity-color scan starts at the message portion
+// and never sees the timestamp's or plugin's own color. The closing bracket `]` never appears inside the SGR sequences the server emits, so scanning the raw line for it
+// is unambiguous. Returns 0 when fewer than two `]` are present (no recognizable prefix), letting the caller scan from the start.
+function messageColorStart(raw) {
+    const firstClose = raw.indexOf("]");
+    if (firstClose === -1) {
+        return 0;
+    }
+    const secondClose = raw.indexOf("]", firstClose + 1);
+    return secondClose === -1 ? 0 : secondClose + 1;
+}
+// Read the severity level from the first severity-mapping SGR color sequence at or after `from` in the raw line, or null when none is present. Scanning from `from`
+// (past the bracket prefix) excludes the timestamp/plugin colors; the first SGR whose parameter maps to a severity wins. An SGR parameter may be a semicolon-separated
+// list (e.g., `1;31` for bold red), so each component is consulted against the severity map. Resets and default-color codes (0, 39) never map, so they are skipped
+// transparently and the genuine severity color is found.
+function readLevel(raw, from) {
+    // Reset the shared global regex's cursor to the scan start. `SGR_PATTERN` carries the `g` flag so successive `.exec` calls walk every SGR sequence in the line; setting
+    // `lastIndex` bounds the walk to the message portion and keeps the module-scope regex stateless across `parseLogLine` calls.
+    SGR_PATTERN.lastIndex = from;
+    for (let match = SGR_PATTERN.exec(raw); match !== null; match = SGR_PATTERN.exec(raw)) {
+        // `match[1]` is the captured parameter string; split on semicolons so a compound SGR like `1;31m` is checked component-by-component against the severity map.
+        const parameters = (match[1] ?? "").split(";");
+        for (const parameter of parameters) {
+            const mapped = SGR_LEVEL[parameter];
+            if (mapped !== undefined) {
+                return mapped;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Parse a Homebridge log timestamp into epoch milliseconds, or `null` when the text is not a recognized timestamp.
+ *
+ * The Homebridge UI renders the first bracketed field as the host's locale/clock string. This recognizes the en-US default in both its renderings - the 12-hour
+ * `M/D/YYYY, h:mm:ss AM` and the 24-hour `M/D/YYYY, HH:mm:ss` - via a single regex, constructs the instant in LOCAL time (matching how the server formats it in the
+ * host's own timezone), and returns its epoch milliseconds. The shared {@link normalizeClock} helper owns the meridiem-to-24-hour conversion and the clock-component
+ * range check, so that rule lives in exactly one place.
+ *
+ * Deliberate limitations, in the same register as the rest of the client: only the en-US 12h/24h default is recognized, so a server running another locale yields
+ * `null` (the time-window stage carries forward the most recent parsed instant, so a null-epoch line is kept iff its parent record is in-window, never dropped merely for
+ * lacking a parseable epoch); and the interpretation is LOCAL time, so a client whose timezone differs from the server's skews the absolute values. A well-formed but
+ * impossible calendar date (for example `2/30`) returns `null`; a wall-clock time that falls in the client's DST spring-forward gap is best-effort accepted rather than
+ * rejected, because only the calendar fields are round-trip-validated.
+ *
+ * @param text - The raw timestamp text from a {@link LogRecord.timestamp} (the first bracketed field), for example `"6/29/2026, 7:00:00 AM"`.
+ *
+ * @returns The instant as epoch milliseconds, or `null` when the text is not a recognized en-US timestamp or names an impossible calendar date.
+ *
+ * @category Log Client
+ */
+export function parseLogTimestamp(text) {
+    const match = LOG_TIMESTAMP_PATTERN.exec(text);
+    if (match === null) {
+        return null;
+    }
+    // The numeric groups are guaranteed present by a successful match; the optional meridiem group is undefined for a 24-hour rendering. We parse the calendar fields
+    // here and delegate the clock fields to `normalizeClock`, which owns the range check and the 12-hour-to-24-hour conversion.
+    const month = Number.parseInt(match[1] ?? "", 10);
+    const day = Number.parseInt(match[2] ?? "", 10);
+    const year = Number.parseInt(match[3] ?? "", 10);
+    const clock = normalizeClock({ hour: Number.parseInt(match[4] ?? "", 10), meridiem: match[7], minute: Number.parseInt(match[5] ?? "", 10),
+        second: Number.parseInt(match[6] ?? "", 10) });
+    // An out-of-range clock component (an impossible hour/minute/second) invalidates the whole timestamp.
+    if (clock === null) {
+        return null;
+    }
+    // Construct the instant in LOCAL time, then round-trip the CALENDAR fields only. The round-trip rejects a well-formed-but-impossible date (the Date constructor rolls
+    // `2/30` forward into March, so the day/month no longer match); we intentionally do NOT round-trip the hour/minute/second, so a wall-clock time in the DST spring-
+    // forward gap survives rather than being rejected. Because both the clock and the calendar are validated, the result is total and needs no `NaN` guard.
+    const date = new Date(year, month - 1, day, clock.hour, clock.minute, clock.second);
+    if ((date.getFullYear() !== year) || (date.getMonth() !== (month - 1)) || (date.getDate() !== day)) {
+        return null;
+    }
+    return date.getTime();
+}
+/**
+ * Normalize a raw clock reading - the captured hour/minute/second plus an optional meridiem token - into a 24-hour `{ hour, minute, second }`, or `null` when any
+ * component is out of range. This is the SINGLE source of truth for the meridiem-to-24-hour conversion and the clock-component range check, shared by
+ * {@link parseLogTimestamp} and the CLI-layer time-expression parser so neither re-implements the rule. It is a named export for those consumers and its own test, but it
+ * is intentionally not part of the package barrel.
+ *
+ * Range rules: minute and second are 0-59 in every rendering; when a meridiem is present the hour is a 12-hour value (1-12), and without one it is a 24-hour value
+ * (0-23). An out-of-range component yields `null`. The conversion maps `12am` to 0 and `12pm` to 12, adds 12 to any other PM hour, and leaves any other AM hour and every
+ * 24-hour reading unchanged.
+ *
+ * @param parts          - The raw clock components.
+ * @param parts.hour     - The hour as written (1-12 with a meridiem, 0-23 without).
+ * @param parts.meridiem - The matched `AM`/`PM` token (any case) when the source carried one, or `undefined` for a 24-hour rendering.
+ * @param parts.minute   - The minute (0-59).
+ * @param parts.second   - The second (0-59).
+ *
+ * @returns The normalized 24-hour `{ hour, minute, second }`, or `null` when any component is out of range.
+ *
+ * @category Log Client
+ */
+export function normalizeClock(parts) {
+    const { hour, meridiem, minute, second } = parts;
+    // Minute and second are 0-59 regardless of rendering; an out-of-range component invalidates the reading.
+    if ((minute < 0) || (minute > 59) || (second < 0) || (second > 59)) {
+        return null;
+    }
+    // No meridiem means a 24-hour reading (0-23) that is already normalized; validate the range and pass it through verbatim.
+    if (meridiem === undefined) {
+        if ((hour < 0) || (hour > 23)) {
+            return null;
+        }
+        return { hour, minute, second };
+    }
+    // A meridiem is present, so the hour is a 12-hour value (1-12).
+    if ((hour < 1) || (hour > 12)) {
+        return null;
+    }
+    // Convert to 24-hour: `12am` is midnight (0) and `12pm` is noon (12); any other PM hour is `+12` and any other AM hour is unchanged.
+    const isPm = meridiem.charAt(0).toLowerCase() === "p";
+    if (hour === 12) {
+        return { hour: isPm ? 12 : 0, minute, second };
+    }
+    return { hour: isPm ? hour + 12 : hour, minute, second };
+}
+/**
+ * Determine whether a raw log line begins a new Homebridge log entry - that is, whether it opens with a parseable bracketed timestamp.
+ *
+ * Every genuine entry the server emits starts with a `[timestamp]` field; a `[plugin]` bracket may or may not follow, because Homebridge's own core lines (for example
+ * `[7/3/2026, 4:31:46 PM] Homebridge v1.11.3 ... is running`) carry a timestamp but no plugin prefix. Only the FIRST bracket is inspected: requiring a second `[plugin]`
+ * bracket would wrongly reject those core lines. A line that is not an entry start - the server's `Loading logs...` / `File: ...` seed preamble, a byte-truncated seed
+ * fragment, or a continuation line such as a stack frame or a wrapped object dump - has no leading parseable timestamp and returns `false`. ANSI is stripped first
+ * because the server wraps the timestamp in an SGR color, so the raw line begins with an escape sequence rather than the `[`.
+ *
+ * @param raw - A single raw log line (escapes intact, terminator already removed by {@link LogLineSplitter}).
+ *
+ * @returns `true` when the line opens with a parseable en-US timestamp bracket, `false` otherwise.
+ *
+ * @category Log Client
+ */
+export function isLogLineStart(raw) {
+    const match = LOG_LINE_START_PATTERN.exec(stripAnsi(raw));
+    return (match !== null) && (parseLogTimestamp(match[1] ?? "") !== null);
+}
+/**
+ * A one-way admission latch that suppresses the unusable leading lines of a live socket log seed until the first genuine log entry.
+ *
+ * The homebridge-config-ui-x native/file log method seeds a live tail by streaming the tail of the log file from a BYTE offset rather than a line boundary, so the first
+ * line of file content is a fragment - the tail end of whatever line the offset fell inside - preceded by the server's own `Loading logs...` / `File: ...` preamble. None
+ * of that is a showable entry. This gate drops every line until the first that begins a real entry - a parseable leading `[timestamp]`, per {@link isLogLineStart} - then
+ * latches OPEN and admits everything thereafter, so the continuation lines and plugin-less core lines that legitimately lack a full prefix flow through untouched.
+ *
+ * It is composed per stream, exactly as {@link LogLineSplitter} is: the consumer owns WHEN to apply it (only on the byte-seeded socket seed - the REST whole-file
+ * download starts at byte 0 and needs no gate), while this owns the latch policy. Once open it never closes, so steady-state admission is a single boolean read and the
+ * recognition predicate runs only across the short leading prefix, never the live stream.
+ *
+ * A bounded safety valve guards the pathological case of a stream whose timestamps are not the recognized en-US rendering (a non-default server locale): if no entry
+ * start is seen within `maxSkip` lines, the gate concludes the format is unrecognized, latches open, and admits the rest rather than suppressing the stream forever.
+ * `maxSkip` is sized above any plausible leading-noise run yet well below the ~500-line seed, so it never fires for a normal log and bounds worst-case loss when it does.
+ *
+ * @example
+ *
+ * ```ts
+ * const gate = new SeedGate(SEED_GATE_MAX_SKIP);
+ *
+ * for(const line of splitter.consume(chunk)) {
+ *
+ *   if(gate.admit(line)) {
+ *
+ *     emit(line);
+ *   }
+ * }
+ * ```
+ *
+ * @category Log Client
+ */
+export class SeedGate {
+    // Whether the latch has opened. Once true, every line is admitted with a single boolean read and the recognition predicate is never consulted again.
+    #open = false;
+    // The number of leading non-entry lines dropped so far while the latch is still closed. Bounded by `#maxSkip`, at which point the gate gives up and opens.
+    #skipped = 0;
+    // The safety-valve bound: the most leading non-entry lines to drop before concluding the stream carries no recognizable entry start and opening the latch regardless.
+    #maxSkip;
+    /**
+     * @param maxSkip - The safety-valve bound: the most leading non-entry lines to drop before opening the latch unconditionally. The consumer injects it (production
+     *                  passes `SEED_GATE_MAX_SKIP`) so a test can drive the bounded-open path with a small value.
+     */
+    constructor(maxSkip) {
+        this.#maxSkip = maxSkip;
+    }
+    /**
+     * Decide whether a raw line is admitted, advancing the latch. Once the latch has opened every line is admitted; before then, only the first line that begins a genuine
+     * entry (which opens the latch) or the line at which the skip bound is reached (the unrecognized-format safety valve) is admitted, and every leading non-entry line is
+     * dropped.
+     *
+     * @param line - A single raw log line from the seed stream.
+     *
+     * @returns `true` if the line should be emitted, `false` if it is leading seed noise to drop.
+     */
+    admit(line) {
+        // Once the first real entry has opened the latch, every subsequent line is admitted with a single boolean read - no re-parsing across the live stream.
+        if (this.#open) {
+            return true;
+        }
+        // The first line that begins a genuine entry opens the latch and is itself admitted.
+        if (isLogLineStart(line)) {
+            this.#open = true;
+            return true;
+        }
+        // Still leading seed noise (the byte-seek fragment, the server preamble, or an orphaned continuation of the truncated entry): drop it - unless we have already
+        // dropped `#maxSkip` lines without seeing an entry start, which means the stream carries no recognized timestamp (an unrecognized locale/format). In that case
+        // stop gating and admit the rest so the stream is never suppressed indefinitely.
+        if (this.#skipped >= this.#maxSkip) {
+            this.#open = true;
+            return true;
+        }
+        this.#skipped++;
+        return false;
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/logclient/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/logclient/parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0BH,sKAAsK;AACtK,sKAAsK;AACtK,sHAAsH;AACtH,4CAA4C;AAC5C,MAAM,YAAY,GAAG,yBAAyB,CAAC;AAE/C,qKAAqK;AACrK,qKAAqK;AACrK,yKAAyK;AACzK,+JAA+J;AAC/J,sKAAsK;AACtK,MAAM,SAAS,GAAuC,MAAM,CAAC,MAAM,CAAC;IAElE,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,OAAO;CACd,CAAC,CAAC;AAEH,+JAA+J;AAC/J,yKAAyK;AACzK,0IAA0I;AAC1I,4CAA4C;AAC5C,MAAM,WAAW,GAAG,gBAAgB,CAAC;AAErC,qKAAqK;AACrK,uKAAuK;AACvK,kKAAkK;AAClK,4BAA4B;AAC5B,MAAM,sBAAsB,GAAG,6BAA6B,CAAC;AAE7D,0KAA0K;AAC1K,qKAAqK;AACrK,mFAAmF;AACnF,MAAM,qBAAqB,GAAG,kFAAkF,CAAC;AAEjH,uKAAuK;AACvK,uKAAuK;AACvK,6GAA6G;AAC7G,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAE/C,oKAAoK;AACpK,iFAAiF;AACjF,SAAS,SAAS,CAAC,IAAY;IAE7B,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,eAAe;IAE1B,kKAAkK;IAClK,gDAAgD;IAChD,MAAM,GAAG,EAAE,CAAC;IAEZ;;;;;;;;;OASG;IACI,CAAC,OAAO,CAAC,KAAa;QAE3B,kKAAkK;QAClK,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QAEpE,qKAAqK;QACrK,6EAA6E;QAC7E,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,MAAM,GAAG,CAAC,CAAC;QAEf,OAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;YAE7B,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAExC,gGAAgG;YAChG,IAAG,CAAC,SAAS,KAAK,IAAI,CAAC,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,EAAE,CAAC;gBAEhD,MAAM,EAAE,CAAC;gBAET,SAAS;YACX,CAAC;YAED,iKAAiK;YACjK,uHAAuH;YACvH,MAAM,OAAO,GAAG,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACjD,MAAM,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;YAE7C,iKAAiK;YACjK,mKAAmK;YACnK,yEAAyE;YACzE,IAAG,CAAC,OAAO,EAAE,CAAC;gBAEZ,MAAM;YACR,CAAC;YAED,+JAA+J;YAC/J,wDAAwD;YACxD,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAElC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC;YAErD,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACzB,KAAK,GAAG,MAAM,CAAC;QACjB,CAAC;QAED,mKAAmK;QACnK,+GAA+G;QAC/G,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;;;OAQG;IACI,CAAC,KAAK;QAEX,IAAG,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAE5B,OAAO;QACT,CAAC;QAED,oKAAoK;QACpK,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAEpD,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QAEjB,MAAM,QAAQ,CAAC;IACjB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IAEtC,iKAAiK;IACjK,8CAA8C;IAC9C,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEpD,IAAG,KAAK,KAAK,IAAI,EAAE,CAAC;QAElB,qKAAqK;QACrK,uHAAuH;QACvH,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC7F,CAAC;IAED,uKAAuK;IACvK,oKAAoK;IACpK,sKAAsK;IACtK,uKAAuK;IACvK,0EAA0E;IAC1E,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC;IAC/C,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAElF,6JAA6J;IAC7J,0CAA0C;IAC1C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;AACzH,CAAC;AAED,sKAAsK;AACtK,yKAAyK;AACzK,kIAAkI;AAClI,SAAS,iBAAiB,CAAC,GAAW;IAEpC,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAG,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QAErB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;IAErD,OAAO,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,oKAAoK;AACpK,uKAAuK;AACvK,mKAAmK;AACnK,yDAAyD;AACzD,SAAS,SAAS,CAAC,GAAW,EAAE,IAAY;IAE1C,wKAAwK;IACxK,6HAA6H;IAC7H,WAAW,CAAC,SAAS,GAAG,IAAI,CAAC;IAE7B,KAAI,IAAI,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,EAAE,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAErF,8JAA8J;QAC9J,MAAM,UAAU,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAE/C,KAAI,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YAElC,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;YAEpC,IAAG,MAAM,KAAK,SAAS,EAAE,CAAC;gBAExB,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAE5C,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE/C,IAAG,KAAK,KAAK,IAAI,EAAE,CAAC;QAElB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kKAAkK;IAClK,4HAA4H;IAC5H,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC;QACvI,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAEjD,sGAAsG;IACtG,IAAG,KAAK,KAAK,IAAI,EAAE,CAAC;QAElB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sKAAsK;IACtK,mKAAmK;IACnK,wJAAwJ;IACxJ,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAEpF,IAAG,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC;QAElG,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAAC,KAA0E;IAEvG,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAEjD,yGAAyG;IACzG,IAAG,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,EAAE,CAAC;QAElE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0HAA0H;IAC1H,IAAG,QAAQ,KAAK,SAAS,EAAE,CAAC;QAE1B,IAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC,EAAE,CAAC;YAE7B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAClC,CAAC;IAED,gEAAgE;IAChE,IAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC,EAAE,CAAC;QAE7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qIAAqI;IACrI,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,GAAG,CAAC;IAEtD,IAAG,IAAI,KAAK,EAAE,EAAE,CAAC;QAEf,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjD,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IAExC,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAE1D,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,QAAQ;IAEnB,qJAAqJ;IACrJ,KAAK,GAAG,KAAK,CAAC;IAEd,2JAA2J;IAC3J,QAAQ,GAAG,CAAC,CAAC;IAEb,sKAAsK;IAC7J,QAAQ,CAAS;IAE1B;;;OAGG;IACH,YAAY,OAAe;QAEzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,IAAY;QAEvB,uJAAuJ;QACvJ,IAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YAEd,OAAO,IAAI,CAAC;QACd,CAAC;QAED,qFAAqF;QACrF,IAAG,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;YAExB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAElB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,+JAA+J;QAC/J,+JAA+J;QAC/J,iFAAiF;QACjF,IAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAElC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAElB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC,QAAQ,EAAE,CAAC;QAEhB,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/logclient/rest.d.ts

@@ -0,0 +1,41 @@
+import type { SocketTarget } from "./endpoints.ts";
+/**
+ * Options accepted by {@link downloadLog}: the connection target plus the raw token, an injectable `fetch` seam, and an optional abort signal.
+ *
+ * @property fetch  - The fetch implementation to use. Defaults to the global `fetch`. Injected so the download flow is testable without a live server.
+ * @property host   - The hostname or IP of the homebridge-config-ui-x server.
+ * @property port   - The TCP port the server listens on.
+ * @property signal - Optional abort signal forwarded to the underlying `fetch`. When it aborts, the in-flight request and the body reader are both cancelled so the
+ *                    connection is released immediately rather than draining to completion in the background. A pre-aborted signal short-circuits the download before any
+ *                    request is made (the platform `fetch` rejects synchronously).
+ * @property tls    - When `true`, use the secure (`https`) scheme; when `false` or omitted, plaintext (`http`).
+ * @property token  - The raw bearer token, sent as `Authorization: Bearer <token>`.
+ *
+ * @category Log Client
+ */
+export interface DownloadLogOptions extends SocketTarget {
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Download the entire Homebridge log file over REST and yield it as raw lines.
+ *
+ * Streams `GET /api/platform-tools/hb-service/log/download?colour=yes` through the shared {@link LogLineSplitter}, yielding each raw line (ANSI intact) as it becomes
+ * available, and flushing the splitter at end-of-response so the file's final line is never stranded. The whole-file download is the deep-history channel: the server
+ * exposes no tail/range parameter, so a caller that only wants the most recent N lines drains this iterable and retains the tail (e.g., via `takeLast`).
+ *
+ * When `options.signal` is supplied, the download is abortable: aborting the signal cancels the in-flight `fetch` and the body reader so the connection is released
+ * immediately rather than draining in the background, and a pre-aborted signal short-circuits before any request is made. This is what lets the windowed hedge supersede
+ * a speculative deep-history download the moment the socket seed is shown to cover the window.
+ *
+ * @param options - The connection target, the raw token, the injectable `fetch` seam, and the optional abort signal. See {@link DownloadLogOptions}.
+ *
+ * @returns An async iterable of raw log lines (escapes intact, terminators removed), in file order.
+ *
+ * @throws `Error` when the server returns a 400 (the log method is not file-backed, so there is no file to download - the message advises `--follow`), or any other
+ *         non-2xx status, or when the response carries no body. Propagates `options.signal`'s reason (typically an `HbpuAbortError`) when the signal aborts.
+ *
+ * @category Log Client
+ */
+export declare function downloadLog(options: DownloadLogOptions): AsyncIterable<string>;
+//# sourceMappingURL=rest.d.ts.map

package/dist/logclient/rest.js

@@ -0,0 +1,111 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * logclient/rest.ts: Streamed whole-file log download from the homebridge-config-ui-x REST API.
+ */
+/**
+ * Streamed REST log retrieval for the Homebridge UI log client.
+ *
+ * {@link downloadLog} fetches the entire log file from `GET /api/platform-tools/hb-service/log/download?colour=yes` and yields it line by line as an
+ * `AsyncIterable<string>` of raw lines (ANSI escapes intact). The server has no range/tail parameter - it always streams the whole file - so this is the deep-history
+ * channel paid only when the user explicitly asks for history beyond the socket's ~500-line seed (see the cost model on `TailRequest` in `types.ts`).
+ *
+ * Two details are load-bearing:
+ *
+ * - The response body is streamed, not buffered. We feed each chunk through the shared {@link LogLineSplitter} so a multi-MB log never has to be materialized in memory
+ *   as one string, and the consumer can begin processing lines as they arrive. The splitter handles lines split across chunk boundaries and the mixed newline
+ *   conventions transparently.
+ * - We MUST call `splitter.flush()` at end-of-response. The splitter withholds a chunk-final lone line-feed pending a possible split `\n\r`/`\r\n` pair in the next
+ *   chunk; at end-of-response no next chunk arrives, so without a flush the final line of the file would be stranded in the carry and silently lost.
+ *
+ * The transport asks for `colour=yes` (the raw file with ANSI intact) rather than `colour=no`, because the server's color stripping shifts byte offsets and, more
+ * importantly, the ANSI color IS the severity-level signal the parser reads. When the log method is `systemd`/`custom` the endpoint returns 400; we map that to a clear
+ * "no log file on disk; use --follow" error rather than surfacing a bare HTTP status.
+ *
+ * The `fetch` implementation is injected (defaulting to the global `fetch`) so the whole flow is exercised in tests without a live server.
+ *
+ * @module
+ */
+import { LogLineSplitter } from "./parser.js";
+import { httpBaseUrl } from "./endpoints.js";
+// Decode a streamed byte chunk to text. We hold a single `TextDecoder` across the whole response with `{ stream: true }` so a multi-byte UTF-8 sequence split across two
+// chunks is reassembled correctly rather than producing a replacement character at the boundary. The final `decode()` with no argument flushes any trailing partial
+// sequence.
+async function* readLines(body, signal) {
+    const splitter = new LogLineSplitter();
+    const decoder = new TextDecoder();
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            // eslint-disable-next-line no-await-in-loop
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            // Decode this chunk (streaming, so a split multi-byte sequence carries into the next read) and feed it to the splitter, yielding every complete raw line the chunk
+            // contained or completed.
+            for (const line of splitter.consume(decoder.decode(value, { stream: true }))) {
+                yield line;
+            }
+        }
+        // Flush the decoder's trailing partial sequence (if any) into the splitter, then flush the splitter's held final line. The splitter withholds a chunk-final lone
+        // line-feed pending a possible cross-chunk pair; at end-of-response no further chunk arrives, so this flush is what surfaces the file's last line rather than
+        // stranding it in the carry.
+        const tail = decoder.decode();
+        if (tail.length > 0) {
+            for (const line of splitter.consume(tail)) {
+                yield line;
+            }
+        }
+        for (const line of splitter.flush()) {
+            yield line;
+        }
+    }
+    finally {
+        // When the download was aborted (the hedge superseded it, or the caller tore the stream down), actively cancel the body first so undici aborts the request and the
+        // connection is released immediately rather than draining to completion in the background as a pinned connection; the cancel's rejection on an already-aborted body
+        // is expected, so it is swallowed. In every case release the reader lock - normal completion, an early `break` by the consumer, or a thrown error - so the underlying
+        // stream is never left locked.
+        if (signal?.aborted) {
+            void reader.cancel().catch(() => { });
+        }
+        reader.releaseLock();
+    }
+}
+/**
+ * Download the entire Homebridge log file over REST and yield it as raw lines.
+ *
+ * Streams `GET /api/platform-tools/hb-service/log/download?colour=yes` through the shared {@link LogLineSplitter}, yielding each raw line (ANSI intact) as it becomes
+ * available, and flushing the splitter at end-of-response so the file's final line is never stranded. The whole-file download is the deep-history channel: the server
+ * exposes no tail/range parameter, so a caller that only wants the most recent N lines drains this iterable and retains the tail (e.g., via `takeLast`).
+ *
+ * When `options.signal` is supplied, the download is abortable: aborting the signal cancels the in-flight `fetch` and the body reader so the connection is released
+ * immediately rather than draining in the background, and a pre-aborted signal short-circuits before any request is made. This is what lets the windowed hedge supersede
+ * a speculative deep-history download the moment the socket seed is shown to cover the window.
+ *
+ * @param options - The connection target, the raw token, the injectable `fetch` seam, and the optional abort signal. See {@link DownloadLogOptions}.
+ *
+ * @returns An async iterable of raw log lines (escapes intact, terminators removed), in file order.
+ *
+ * @throws `Error` when the server returns a 400 (the log method is not file-backed, so there is no file to download - the message advises `--follow`), or any other
+ *         non-2xx status, or when the response carries no body. Propagates `options.signal`'s reason (typically an `HbpuAbortError`) when the signal aborts.
+ *
+ * @category Log Client
+ */
+export async function* downloadLog(options) {
+    const fetchImpl = options.fetch ?? fetch;
+    const url = httpBaseUrl(options) + "/api/platform-tools/hb-service/log/download?colour=yes";
+    const response = await fetchImpl(url, { headers: { "Authorization": "Bearer " + options.token }, method: "GET", signal: options.signal });
+    // A 400 from this endpoint means the configured log method is not file-backed (systemd/custom), so there is no file on disk to download. Map it to an actionable
+    // message that points the user at the live-tail channel rather than surfacing a bare status code.
+    if (response.status === 400) {
+        throw new Error("No log file is available to download on disk (the Homebridge log method is not file-backed); use --follow to live-tail instead.");
+    }
+    if (!response.ok) {
+        throw new Error("Log download failed - the server returned HTTP " + response.status.toString() + " (" + response.statusText + ").");
+    }
+    if (response.body === null) {
+        throw new Error("Log download failed - the server returned an empty response body.");
+    }
+    yield* readLines(response.body, options.signal);
+}
+//# sourceMappingURL=rest.js.map

package/dist/logclient/rest.js.map

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

package/dist/logclient/settings.d.ts

@@ -0,0 +1,15 @@
+export declare const DEFAULT_HOST = "localhost";
+export declare const DEFAULT_PORT = 8581;
+export declare const LOG_NAMESPACE = "log";
+export declare const SOCKET_PATH = "/socket.io/";
+export declare const PTY_COLUMNS = 80;
+export declare const PTY_ROWS = 24;
+export declare const RECONNECT_BASE_MS = 500;
+export declare const RECONNECT_CAP_MS = 5000;
+export declare const JITTER_FRACTION = 0.5;
+export declare const MARGIN_MS = 5000;
+export declare const SEED_QUIESCENCE_MS = 250;
+export declare const SEED_SETTLE_MS = 1000;
+export declare const SEED_WINDOW_MAX_MS = 5000;
+export declare const SEED_GATE_MAX_SKIP = 100;
+//# sourceMappingURL=settings.d.ts.map