homebridge-plugin-utils 1.35.0 → 2.1.0

package/dist/logclient/frame.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A decoded protocol event, discriminated on `kind`.
+ *
+ * The union collapses the two-layer Engine.IO/Socket.IO wire format into the handful of events the log client actually reacts to: the Engine.IO handshake (`open`) and
+ * heartbeat (`ping`/`pong`), and the Socket.IO namespace lifecycle (`namespaceConnect`/`namespaceError`) and payload delivery (`message`). Any unrecognized string
+ * frame the codec does not model - an empty frame, an unknown Engine.IO digit, or an unhandled Socket.IO packet type - decodes to `unknown` carrying the original text,
+ * so a consumer can log it without the codec having to model every Engine.IO/Socket.IO packet type that the log stream never exercises.
+ *
+ * @category Log Client
+ */
+export type ProtocolEvent = {
+    readonly kind: "message";
+    readonly event: string;
+    readonly namespace: string;
+    readonly payload: unknown;
+} | {
+    readonly kind: "namespaceConnect";
+    readonly namespace: string;
+} | {
+    readonly kind: "namespaceError";
+    readonly namespace: string;
+    readonly reason: unknown;
+} | {
+    readonly kind: "open";
+    readonly pingInterval: number;
+    readonly pingTimeout: number;
+} | {
+    readonly kind: "ping";
+} | {
+    readonly kind: "pong";
+} | {
+    readonly kind: "unknown";
+    readonly raw: string;
+};
+/**
+ * An outbound protocol event to serialize, discriminated on `kind`.
+ *
+ * The OutboundEvent union models three frame shapes: a namespace connect (`connect`), a namespace event with a JSON payload (`event` - this is how `tail-log` is
+ * requested), and a heartbeat pong (`pong`). A fourth outbound frame, the namespace DISCONNECT, is hand-assembled separately (see {@link LOG_NAMESPACE_PATH}) because its
+ * fixed, argument-free shape needs no serialization through this codec. Modeling the outbound set as its own narrow union keeps {@link encodeFrame} total over exactly
+ * what it models, rather than re-using the wider inbound {@link ProtocolEvent} and leaving unserializable arms.
+ *
+ * @category Log Client
+ */
+export type OutboundEvent = {
+    readonly args: unknown;
+    readonly event: string;
+    readonly kind: "event";
+    readonly namespace: string;
+} | {
+    readonly kind: "connect";
+    readonly namespace: string;
+} | {
+    readonly kind: "pong";
+};
+/**
+ * Serialize an outbound protocol event to its Engine.IO/Socket.IO wire text.
+ *
+ * Always emits EIO4-shaped frames: a namespace connect is `40<nsPrefix>`, an event is `42<nsPrefix>[event,args]`, and a pong is the bare Engine.IO `"3"`. The event
+ * payload is `JSON.stringify`d as the `[eventName, args]` array the Socket.IO EVENT format requires.
+ *
+ * @param event - The outbound event to serialize. See {@link OutboundEvent}.
+ *
+ * @returns The wire text to send as a single WebSocket message.
+ *
+ * @category Log Client
+ */
+export declare function encodeFrame(event: OutboundEvent): string;
+/**
+ * Decode a single inbound WebSocket frame into a {@link ProtocolEvent}.
+ *
+ * The decoder peels the leading Engine.IO packet-type digit and dispatches: `0` is the handshake open (whose JSON carries the ping interval/timeout), `2`/`3` are the
+ * heartbeat, and `4` is a message whose remaining text is a Socket.IO packet decoded by the inner namespace/event parser. Its input is typed `string` - the composing
+ * socket drops binary frames before they reach the decoder - so any unrecognized STRING frame (an empty frame, an unknown Engine.IO digit, or an unhandled Socket.IO
+ * packet type) decodes to `unknown` carrying the original text.
+ *
+ * @param frame - The raw WebSocket message text.
+ *
+ * @returns The decoded protocol event.
+ *
+ * @category Log Client
+ */
+export declare function decodeFrame(frame: string): ProtocolEvent;
+/**
+ * The Socket.IO namespace, with its leading slash, that the log stream is served on. The wire format addresses namespaces with a leading slash (`/log`), whereas the
+ * `LOG_NAMESPACE` setting holds the bare name (`log`). This constant supplies the slash-prefixed namespace token used to hand-assemble the raw Socket.IO disconnect frame
+ * (`"41/log,"`), where {@link encodeFrame} is bypassed. It must NOT be passed to `encodeFrame`: that codec's connect and event arms take the bare `LOG_NAMESPACE` and
+ * derive the leading slash themselves, so handing them `LOG_NAMESPACE_PATH` would prepend a second slash and emit a malformed `"//log,"` prefix.
+ *
+ * @category Log Client
+ */
+export declare const LOG_NAMESPACE_PATH: string;
+//# sourceMappingURL=frame.d.ts.map

package/dist/logclient/frame.js

@@ -0,0 +1,203 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * logclient/frame.ts: Pure Engine.IO / Socket.IO wire codec for the log namespace.
+ */
+/**
+ * Pure Engine.IO / Socket.IO v4 wire codec.
+ *
+ * The log client speaks raw Engine.IO over a single WebSocket: each WebSocket message is exactly one Engine.IO packet (no `\x1e` payload batching, since batching is an
+ * HTTP-long-polling concern, not a WebSocket one), and a Socket.IO packet is layered inside an Engine.IO `message` packet. This module is the single source of truth for
+ * that two-layer framing - the Engine.IO packet-type digits (`0` open, `2` ping, `3` pong, `4` message), the Socket.IO packet-type digits inside a message (`0` CONNECT,
+ * `2` EVENT, `4` CONNECT_ERROR), and the `/log,` namespace prefix. It is deliberately pure and stateless, mirroring the `mp4-parser.ts` / `rtp-parser.ts` pure-parser
+ * precedent: it turns wire text into a {@link ProtocolEvent} discriminated union and back, and leaves all I/O, liveness, and lifecycle to the composing socket.
+ *
+ * `allowEIO3` interop: the server is started with `allowEIO3: true`, so a downgraded EIO3 client would see the Socket.IO CONNECT acknowledgement as a bare `40` with no
+ * namespace and no trailing payload, where EIO4 sends `40/log,{"sid":"..."}`. {@link decodeFrame} treats both shapes as a namespace-connect for whichever namespace the
+ * frame names (defaulting to the root namespace when none is present), so a consumer reading the decoded `kind` does not have to branch on the negotiated protocol
+ * version. We always emit EIO4-shaped frames from {@link encodeFrame}; the interop only matters on the decode side.
+ *
+ * @module
+ */
+import { LOG_NAMESPACE } from "./settings.js";
+// The Engine.IO packet-type digit for an `open` packet: the server's first frame, carrying the session handshake JSON (ping interval/timeout, sid).
+const ENGINE_OPEN = "0";
+// The Engine.IO packet-type digit for a `ping`. Under the WebSocket transport in EIO4 the server is the pinger, so an inbound `"2"` is a server ping the client must
+// answer with a `"3"` pong.
+const ENGINE_PING = "2";
+// The Engine.IO packet-type digit for a `pong`. Surfaced for completeness on decode; the client emits one via {@link encodeFrame} in response to each server ping.
+const ENGINE_PONG = "3";
+// The Engine.IO packet-type digit for a `message`: the envelope that carries a Socket.IO packet as its remaining text.
+const ENGINE_MESSAGE = "4";
+// The Socket.IO packet-type digit (inside an Engine.IO message) for a namespace CONNECT acknowledgement.
+const SOCKET_CONNECT = "0";
+// The Socket.IO packet-type digit for an EVENT - the packet that carries `[eventName, ...args]` JSON, which is how the server delivers `stdout` log chunks.
+const SOCKET_EVENT = "2";
+// The Socket.IO packet-type digit for a CONNECT_ERROR - the server's rejection of a namespace connect (e.g., an auth failure surfaced at the namespace layer).
+const SOCKET_CONNECT_ERROR = "4";
+// Build the Socket.IO namespace prefix that addresses a frame at a namespace. The root namespace ("/") is implicit on the wire and carries no prefix; any other
+// namespace is emitted as `/<name>,` - note the leading slash the server expects and the trailing comma that terminates the namespace token. Centralized here so both
+// the connect and event encoders address namespaces identically.
+function namespacePrefix(namespace) {
+    if (namespace === "/") {
+        return "";
+    }
+    return "/" + namespace + ",";
+}
+/**
+ * Serialize an outbound protocol event to its Engine.IO/Socket.IO wire text.
+ *
+ * Always emits EIO4-shaped frames: a namespace connect is `40<nsPrefix>`, an event is `42<nsPrefix>[event,args]`, and a pong is the bare Engine.IO `"3"`. The event
+ * payload is `JSON.stringify`d as the `[eventName, args]` array the Socket.IO EVENT format requires.
+ *
+ * @param event - The outbound event to serialize. See {@link OutboundEvent}.
+ *
+ * @returns The wire text to send as a single WebSocket message.
+ *
+ * @category Log Client
+ */
+export function encodeFrame(event) {
+    switch (event.kind) {
+        case "connect": {
+            // A namespace CONNECT is an Engine.IO message (`4`) wrapping a Socket.IO CONNECT (`0`), addressed at the namespace.
+            return ENGINE_MESSAGE + SOCKET_CONNECT + namespacePrefix(event.namespace);
+        }
+        case "event": {
+            // A namespace EVENT is an Engine.IO message (`4`) wrapping a Socket.IO EVENT (`2`), addressed at the namespace, followed by the `[eventName, args]` JSON array.
+            return ENGINE_MESSAGE + SOCKET_EVENT + namespacePrefix(event.namespace) + JSON.stringify([event.event, event.args]);
+        }
+        case "pong": {
+            // A pong is a bare Engine.IO packet with no Socket.IO layer.
+            return ENGINE_PONG;
+        }
+        default: {
+            // Every OutboundEvent arm above returns, so this `default` is an unreachable fallback that yields an empty string; it provides no compile-time exhaustiveness
+            // guard, so a future arm added without its own case would silently fall through to this empty frame rather than failing to compile.
+            return "";
+        }
+    }
+}
+// Parse the Socket.IO body that follows the Engine.IO message digit. The body is `<socketDigit>[<nsPrefix>][<ackId>][<json>]`; we peel each segment in order and return
+// the resulting protocol event. Kept as a focused helper so {@link decodeFrame} stays a readable Engine.IO-layer switch.
+function decodeSocketMessage(body) {
+    const socketDigit = body.charAt(0);
+    let rest = body.slice(1);
+    // Peel an optional namespace prefix. A namespaced frame begins with `/`; the namespace token runs up to (and is terminated by) the first comma. When no leading slash
+    // is present the frame addresses the root namespace, which carries no prefix on the wire.
+    let namespace = "/";
+    if (rest.startsWith("/")) {
+        const comma = rest.indexOf(",");
+        // A namespace prefix without its terminating comma is malformed; treat the whole remainder as the namespace and leave nothing for the payload, which the JSON peel
+        // below tolerates as an empty body.
+        if (comma === -1) {
+            namespace = rest.slice(1);
+            rest = "";
+        }
+        else {
+            namespace = rest.slice(1, comma);
+            rest = rest.slice(comma + 1);
+        }
+    }
+    switch (socketDigit) {
+        case SOCKET_CONNECT: {
+            // A namespace CONNECT acknowledgement. EIO4 carries a `{"sid":"..."}` payload we do not need; EIO3 (under `allowEIO3`) carries nothing. Either way the event is a
+            // namespace connect for the named namespace - the payload is intentionally discarded.
+            return { kind: "namespaceConnect", namespace };
+        }
+        case SOCKET_CONNECT_ERROR: {
+            // A namespace CONNECT_ERROR. The trailing JSON, when present, is the server's rejection reason (often `{ message }`); we surface it verbatim as `reason` for the
+            // consumer to render. A malformed or absent reason decodes to `null`.
+            return { kind: "namespaceError", namespace, reason: safeJsonParse(rest) };
+        }
+        case SOCKET_EVENT: {
+            // A namespace EVENT carrying `[eventName, ...args]`. Peel an optional numeric ack id that may precede the JSON payload (the server does not request acks on the
+            // log stream, but the format permits one, so we skip leading digits before the first JSON-value start character: `[`, `{`, or `"`). The first array element is
+            // the event name; the second is the payload we forward.
+            const jsonStart = rest.search(/[[{"]/);
+            const json = jsonStart === -1 ? rest : rest.slice(jsonStart);
+            const parsed = safeJsonParse(json);
+            if (!Array.isArray(parsed) || (parsed.length === 0) || (typeof parsed[0] !== "string")) {
+                // An EVENT whose body is not a `[stringEventName, ...]` array is not something we can route; surface it as unknown rather than fabricating an event name.
+                return { kind: "unknown", raw: ENGINE_MESSAGE + body };
+            }
+            return { event: parsed[0], kind: "message", namespace, payload: parsed.length > 1 ? parsed[1] : undefined };
+        }
+        default: {
+            // Any other Socket.IO packet type (ACK, BINARY_EVENT, BINARY_ACK, DISCONNECT) is not part of the log stream's vocabulary; surface the original message frame as
+            // unknown so the consumer can log it without us modeling packet types the stream never produces.
+            return { kind: "unknown", raw: ENGINE_MESSAGE + body };
+        }
+    }
+}
+// Parse JSON, returning `null` rather than throwing on malformed input. The wire is a trusted server, but a partial or non-JSON body must not crash the decoder; the
+// caller treats a `null` result as "no structured payload."
+function safeJsonParse(text) {
+    if (text.length === 0) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decode a single inbound WebSocket frame into a {@link ProtocolEvent}.
+ *
+ * The decoder peels the leading Engine.IO packet-type digit and dispatches: `0` is the handshake open (whose JSON carries the ping interval/timeout), `2`/`3` are the
+ * heartbeat, and `4` is a message whose remaining text is a Socket.IO packet decoded by the inner namespace/event parser. Its input is typed `string` - the composing
+ * socket drops binary frames before they reach the decoder - so any unrecognized STRING frame (an empty frame, an unknown Engine.IO digit, or an unhandled Socket.IO
+ * packet type) decodes to `unknown` carrying the original text.
+ *
+ * @param frame - The raw WebSocket message text.
+ *
+ * @returns The decoded protocol event.
+ *
+ * @category Log Client
+ */
+export function decodeFrame(frame) {
+    // An empty frame carries no packet-type digit; classify it as unknown rather than indexing into nothing.
+    if (frame.length === 0) {
+        return { kind: "unknown", raw: frame };
+    }
+    const engineDigit = frame.charAt(0);
+    const body = frame.slice(1);
+    switch (engineDigit) {
+        case ENGINE_OPEN: {
+            // The Engine.IO open handshake. Its JSON body carries `pingInterval` and `pingTimeout` (milliseconds), which the socket uses to size its liveness watchdog. A
+            // malformed or absent handshake decodes to zero intervals, which the consumer treats as "fall back to defaults."
+            const handshake = safeJsonParse(body);
+            const intervalValue = isRecord(handshake) ? handshake["pingInterval"] : undefined;
+            const timeoutValue = isRecord(handshake) ? handshake["pingTimeout"] : undefined;
+            const pingInterval = (typeof intervalValue === "number") ? intervalValue : 0;
+            const pingTimeout = (typeof timeoutValue === "number") ? timeoutValue : 0;
+            return { kind: "open", pingInterval, pingTimeout };
+        }
+        case ENGINE_PING: {
+            return { kind: "ping" };
+        }
+        case ENGINE_PONG: {
+            return { kind: "pong" };
+        }
+        case ENGINE_MESSAGE: {
+            return decodeSocketMessage(body);
+        }
+        default: {
+            return { kind: "unknown", raw: frame };
+        }
+    }
+}
+// Narrow an unknown value to a plain record so its properties can be read without unsafe member access. Used to read the handshake JSON's numeric fields defensively.
+function isRecord(value) {
+    return (typeof value === "object") && (value !== null);
+}
+/**
+ * The Socket.IO namespace, with its leading slash, that the log stream is served on. The wire format addresses namespaces with a leading slash (`/log`), whereas the
+ * `LOG_NAMESPACE` setting holds the bare name (`log`). This constant supplies the slash-prefixed namespace token used to hand-assemble the raw Socket.IO disconnect frame
+ * (`"41/log,"`), where {@link encodeFrame} is bypassed. It must NOT be passed to `encodeFrame`: that codec's connect and event arms take the bare `LOG_NAMESPACE` and
+ * derive the leading slash themselves, so handing them `LOG_NAMESPACE_PATH` would prepend a second slash and emit a malformed `"//log,"` prefix.
+ *
+ * @category Log Client
+ */
+export const LOG_NAMESPACE_PATH = "/" + LOG_NAMESPACE;
+//# sourceMappingURL=frame.js.map

package/dist/logclient/frame.js.map

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

package/dist/logclient/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The log client's public surface, re-exported for consumption through the package barrel (`import { HomebridgeLogClient } from "homebridge-plugin-utils"`).
+ *
+ * This is a curated barrel, not an `export *` of every module: the subsystem has a deliberate public/internal split. The consumer-facing engine (the client, its options
+ * and stream type, the domain vocabulary, the line parser/splitter, the filter), the dependency-inversion seams power users need to substitute their own transport (the
+ * socket and WebSocket factories plus their production defaults), the lower-level transports that power users may compose directly (`acquireToken`, `downloadLog`,
+ * `LogSocket`), and the reusable test doubles are surfaced here. The purely-internal machinery - the Engine.IO/Socket.IO frame codec, the history-plus-live stitch, the
+ * URL builders, the scalar settings, the time-range internals (`parseTimeExpression`, `timeWindow`, `normalizeClock`), and the CLI layer (`config.ts`, `cli-run.ts`,
+ * `cli.ts`) - is intentionally NOT re-exported, so those internals can be refactored without a breaking change to the published surface. Every symbol below carries an
+ * `@category Log Client` tag (or `@category Testing` for the doubles).
+ *
+ * The CLI bin (`cli.ts`) does not ride this barrel: a bin must reach its engine through a realpath-canonicalized dynamic import rather than a package specifier, so it is
+ * deliberately absent here. See `cli.ts` for that rationale.
+ *
+ * @module
+ */
+export type { LogClientCredentials, LogLevel, LogQuantity, LogRecord, TailRequest } from "./types.ts";
+export type { HomebridgeLogClientOptions, LogStream } from "./client.ts";
+export type { LogSocketFactory, LogSocketInit, LogSocketLike, TokenProvider, WebSocketFactory, WebSocketLike } from "./socket.ts";
+export type { AcquireTokenOptions, LogAuthErrorKind, LogAuthErrorOptions } from "./auth.ts";
+export type { DownloadLogOptions } from "./rest.ts";
+export type { LogFilterCriteria } from "./filter.ts";
+export type { TestLogSocketInit } from "./socket-double.ts";
+export { LogSocket, WEBSOCKET_OPEN, logSocketFactory, reconnectBackoff, webSocketFactory } from "./socket.ts";
+export { LogAuthError, acquireToken, isPermanentAuthError } from "./auth.ts";
+export { LogLineSplitter, parseLogLine, parseLogTimestamp } from "./parser.ts";
+export { TestLogSocket, TestLogSocketFactory, TestWebSocket, TestWebSocketFactory } from "./socket-double.ts";
+export { HomebridgeLogClient } from "./client.ts";
+export { createLogFilter } from "./filter.ts";
+export { downloadLog } from "./rest.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/logclient/index.js

@@ -0,0 +1,12 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * logclient/index.ts: Public barrel for the Homebridge UI log client (the hblog engine).
+ */
+export { LogSocket, WEBSOCKET_OPEN, logSocketFactory, reconnectBackoff, webSocketFactory } from "./socket.js";
+export { LogAuthError, acquireToken, isPermanentAuthError } from "./auth.js";
+export { LogLineSplitter, parseLogLine, parseLogTimestamp } from "./parser.js";
+export { TestLogSocket, TestLogSocketFactory, TestWebSocket, TestWebSocketFactory } from "./socket-double.js";
+export { HomebridgeLogClient } from "./client.js";
+export { createLogFilter } from "./filter.js";
+export { downloadLog } from "./rest.js";
+//# sourceMappingURL=index.js.map

package/dist/logclient/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logclient/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyBH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9G,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9G,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/logclient/parser.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Pure, incremental text-to-{@link LogRecord} parsing for the Homebridge UI log stream.
+ *
+ * The pure pieces that live here, shared by the socket and REST transports, are:
+ *
+ * - {@link LogLineSplitter} - a cursor-based incremental splitter that turns an unbounded stream of text chunks (from a WebSocket `stdout` event or a streamed REST
+ *   download) into discrete raw lines, transparently handling lines split across chunk boundaries and the four newline conventions the stream mixes.
+ * - {@link parseLogLine} - a per-line parser that extracts the timestamp/plugin brackets and the ANSI-color-derived severity level, producing a {@link LogRecord} whose
+ *   `message` is ANSI-stripped and whose `raw` preserves the original escapes.
+ *
+ * A third pure function, {@link parseLogTimestamp} (with its shared {@link normalizeClock} clock-rule helper), interprets a {@link LogRecord.timestamp} string as an
+ * epoch instant on demand. It is deliberately separate from {@link parseLogLine}, which leaves the timestamp as text: the epoch is a cold, cheaply-derivable value that
+ * only the time-range query path needs, so it is computed by this one shared function when required rather than eagerly materialized on every parsed line.
+ *
+ * This module is the single owner of the ANSI escape regex and the SGR-code-to-{@link LogLevel} map - they live beside the parser that uses them, not in `settings.ts`
+ * (which holds only scalars). The design mirrors the library's per-consumer incremental-assembly pattern (`process.ts`, `mp4-assembler.ts`): rather than sharing a
+ * splitter core with `process.ts`, this splitter is purpose-built, because the two have opposite control-character requirements - `process.ts` strips non-printable
+ * control characters to `os.EOL`, whereas this splitter must PRESERVE control characters because the ANSI color sequence IS the severity data.
+ *
+ * @module
+ */
+import type { LogRecord } from "./types.ts";
+import type { Nullable } from "../util.ts";
+/**
+ * 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 declare class LogLineSplitter {
+    #private;
+    /**
+     * 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: string): Iterable<string>;
+    /**
+     * 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(): Iterable<string>;
+}
+/**
+ * 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 declare function parseLogLine(raw: string): LogRecord;
+/**
+ * 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 declare function parseLogTimestamp(text: string): Nullable<number>;
+/**
+ * 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 declare function normalizeClock(parts: {
+    hour: number;
+    meridiem?: string;
+    minute: number;
+    second: number;
+}): Nullable<{
+    hour: number;
+    minute: number;
+    second: number;
+}>;
+/**
+ * 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 declare function isLogLineStart(raw: string): boolean;
+/**
+ * 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 declare class SeedGate {
+    #private;
+    /**
+     * @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: number);
+    /**
+     * 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: string): boolean;
+}
+//# sourceMappingURL=parser.d.ts.map