homebridge-plugin-utils 1.35.0 → 2.1.0

package/dist/backpressure.js

@@ -1,136 +1,272 @@
 /* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * backpressure.ts: Backpressure-aware write queue for Node.js writable streams.
+ * backpressure.ts: Signal-driven, backpressure-aware write queue for Node.js writable streams.
  */
 /**
- * A backpressure-aware write queue that serializes writes to a writable stream, pausing when the stream signals backpressure and resuming on drain.
+ * AsyncDisposable write queue that serializes Buffer writes onto a Node {@link Writable}, respects backpressure via the stream's `drain` event, and composes into the
+ * library's `AbortSignal`-driven lifecycle so a parent signal can tear the writer down uniformly with every other HBPU resource class.
  *
- * The stream is resolved lazily via a getter function on each write, allowing the writer to be created before the stream exists and to handle stream replacement across
- * process restarts.
+ * Primary use case: feeding fMP4 segments from a livestream event source into an FFmpeg process's stdin, where the downstream may not consume as fast as the upstream
+ * produces.
+ *
+ * @module
+ */
+import { HbpuAbortError, composeSignals, onAbort } from "./util.js";
+import { once } from "node:events";
+/**
+ * Thrown synchronously by {@link BackpressureWriter.write} when the pending queue is already at the configured {@link BackpressureWriterInit.highWaterMark} and
+ * accepting the new chunk would push it over.
+ *
+ * Separate from the "writer has aborted" and "underlying stream is dead" failure modes so callers can distinguish backpressure-overflow (back off and retry later)
+ * from terminal failures (give up or escalate) by type rather than by inspecting error message text.
+ *
+ * @category Utilities
+ */
+export class BackpressureOverflowError extends Error {
+    name = "BackpressureOverflowError";
+    constructor(message = "BackpressureWriter: queue depth exceeds configured highWaterMark.") {
+        super(message);
+    }
+}
+/**
+ * Rejected by an individual {@link BackpressureWriter.write} promise when the provider returned a {@link Writable} whose `writable` flag is `false` (the stream has
+ * ended or been destroyed). The writer itself remains alive - a later stream replacement via the provider may revive the pipeline - so this is a per-write rejection,
+ * not a terminal writer error.
+ *
+ * @category Utilities
+ */
+export class BackpressureClosedStreamError extends Error {
+    name = "BackpressureClosedStreamError";
+    constructor(message = "BackpressureWriter: underlying stream is not writable.") {
+        super(message);
+    }
+}
+/**
+ * AsyncDisposable backpressure-aware write queue for Node {@link Writable} streams.
+ *
+ * Each call to {@link BackpressureWriter.write} returns a Promise that resolves once the chunk has been written (and any triggered backpressure has drained) or rejects
+ * if the writer aborts mid-write. Concurrent writes serialize through an internal FIFO queue; ordering matches call order. The stream itself is resolved lazily through
+ * a caller-supplied provider on each drain turn, so the writer may outlive any particular stream instance - the provider is consulted per chunk, and a `null` return is
+ * a signal to drop the chunk (the associated write promise still resolves, treating the drop as a success from the caller's perspective).
  *
  * @example
  *
  * ```ts
- * // Create a writer that feeds segments to an FFmpeg process stdin.
- * const writer = new BackpressureWriter(() => ffmpegProcess.stdin ?? null);
+ * import { BackpressureWriter } from "homebridge-plugin-utils";
  *
- * // Enqueue segments as they arrive from a livestream source.
- * livestream.on("segment", (segment) => writer.write(segment));
+ * await using writer = new BackpressureWriter(() => ffmpegProcess.stdin ?? null, { signal: session.signal });
  *
- * // When the session ends, close the writer to release pending data.
- * writer.close();
+ * // Each write awaits its own flush; concurrent writes queue behind prior ones.
+ * await writer.write(segmentOne);
+ * await writer.write(segmentTwo);
  * ```
  *
  * @category Utilities
  */
 export class BackpressureWriter {
-    drainListener;
-    drainStream;
-    getStream;
-    isClosed;
-    isWriting;
-    onWrite;
-    queue;
     /**
-     * Creates a new backpressure-aware write queue.
+     * The composed abort signal representing this writer's lifetime. Aborts exactly once when {@link BackpressureWriter.abort} is called, when the parent signal fires,
+     * or when the underlying stream surfaces an error that invalidates the writer; `signal.reason` names the cause.
+     */
+    signal;
+    // The private AbortController whose signal is composed into `this.signal`. Owning the controller internally keeps teardown reachable from any handler - drain-wait
+    // cancellation, stream-error escalation, explicit abort - without giving callers a handle to the raw controller.
+    #controller;
+    // Optional queue-depth ceiling. When undefined, the queue is unbounded and the only memory discipline is whatever the caller imposes by awaiting prior writes before
+    // issuing new ones.
+    #highWaterMark;
+    // Caller-provided resolver for the target stream. Evaluated lazily on each drain-loop iteration so the writer can survive stream replacement across FFmpeg process
+    // restarts, and so callers can bind the writer to a stream that does not yet exist at construction time.
+    #streamProvider;
+    // FIFO queue of pending writes. Each entry pairs the buffer with its resolver so the drain loop can settle the caller's promise at the same point it consumes the
+    // chunk. The drain loop peeks `queue[0]` during the write (so queue.length reflects total pending, including the in-flight entry) and shifts the entry off only
+    // after it has fully flushed or failed.
+    #queue = [];
+    // The active drain-loop promise, if any. Held so `[Symbol.asyncDispose]` can await actual completion before returning, so `await using` callers are guaranteed no
+    // stream interaction is still in flight by the time the surrounding scope exits.
+    #drainTask;
+    // True while the drain loop is active (set at entry, cleared in the loop's `finally`). Used by `write()` to decide whether to spawn a new drain - the flag flips
+    // back to false the moment the loop exits, whether synchronously (queue emptied in one pass, no backpressure) or asynchronously (after a drain wait or abort) - so
+    // a subsequent `write()` that arrives right after an empty-queue exit correctly re-spawns the loop rather than being stranded by a stale drain-task reference.
+    #processing = false;
+    /**
+     * Construct a new backpressure-aware writer.
      *
-     * @param getStream    - A function that returns the current writable stream, or `null` if the stream is unavailable. Evaluated on each write attempt, allowing the
-     *                        writer to be created before the stream exists or to track a stream that changes across process restarts. For a static stream, wrap it in an
-     *                        arrow function: `() => stream`.
-     * @param onWrite      - Optional. A callback invoked after each segment is successfully written to the underlying stream. Useful for tracking write statistics.
+     * @param streamProvider - A function that returns the current writable stream, or `null` to drop incoming chunks. Evaluated lazily on each drain-loop iteration.
+     * @param init           - Optional init options. See {@link BackpressureWriterInit}.
      *
      * @example
      *
      * ```ts
-     * // Lazy resolution...the stream is resolved on each write.
-     * const writer = new BackpressureWriter(() => this.ffmpegProcess?.stdin ?? null, () => segmentCount++);
-     *
-     * // Static stream...wrap in an arrow function.
-     * const writer = new BackpressureWriter(() => stream);
+     * await using writer = new BackpressureWriter(() => this.ffmpegProcess?.stdin ?? null, { highWaterMark: 64, signal: session.signal });
      * ```
      */
-    constructor(getStream, onWrite) {
-        this.drainListener = null;
-        this.drainStream = null;
-        this.getStream = getStream;
-        this.isClosed = false;
-        this.isWriting = false;
-        this.onWrite = onWrite ?? null;
-        this.queue = [];
+    constructor(streamProvider, init = {}) {
+        this.#streamProvider = streamProvider;
+        this.#highWaterMark = init.highWaterMark;
+        this.#controller = new AbortController();
+        this.signal = composeSignals(init.signal, this.#controller.signal);
+        // Single teardown convergence point. `onAbort` registers the one-shot teardown handler AND handles the pre-aborted-signal edge case where `addEventListener`
+        // would otherwise skip the handler. Rejects every pending entry - including the in-flight entry when the drain loop is parked on
+        // `events.once(stream, "drain", { signal })`. The drain loop's catch branch may also reject the in-flight resolver under the same abort; promise resolvers are
+        // inert after first settlement, so the second call is a no-op. Rejecting from here unconditionally is required in the stream-error escalation path,
+        // where the drain loop shifts the in-flight entry before calling `this.#controller.abort(...)` - by the time the listener runs, only the queued entries remain
+        // in the queue, and leaving any of them unrejected would orphan the caller's promise.
+        onAbort(this.signal, () => this.#teardown());
     }
     /**
-     * Enqueues data to be written to the stream. If the stream is available and not under backpressure, the data is written immediately. Otherwise, it is queued and
-     * written when the stream signals it is ready via the drain event.
+     * Enqueue `chunk` for writing. Concurrent calls serialize in FIFO order via the internal queue.
+     *
+     * @param chunk - The buffer to write.
      *
-     * @param data         - The buffer to write to the stream.
+     * @returns A promise that resolves when the chunk has been flushed to the underlying stream (including any required drain wait), or immediately if the provider
+     *          returned `null` at dispatch time (drop semantics). The promise rejects in the following cases:
      *
-     * @returns Returns `true` if the data was accepted (stream is available), `false` if the stream is unavailable or the writer has been closed.
+     * - `this.signal.reason` - the writer aborted before or during the write.
+     * - {@link BackpressureOverflowError} (thrown synchronously) - `highWaterMark` is configured and the queue depth already equals or exceeds it.
+     * - {@link BackpressureClosedStreamError} - the provider returned a stream whose `writable` flag is `false`. The writer itself stays alive for a potential later
+     *   stream replacement.
+     *
+     * @throws {@link BackpressureOverflowError} when `highWaterMark` is exceeded.
+     */
+    async write(chunk) {
+        // Pre-aborted short-circuit: a write issued after teardown has nothing live to attach to. Rejecting with the signal's reason keeps semantics uniform with the
+        // mid-write abort path - callers branch on `signal.reason` / `isHbpuAbortReason` in either case.
+        if (this.signal.aborted) {
+            throw this.signal.reason;
+        }
+        // Queue-overflow fail-fast. Rejecting synchronously lets upstream producers apply their own pacing rather than silently accumulating unbounded backlog. A
+        // dedicated {@link BackpressureOverflowError} class (not an `HbpuAbortError`) is thrown here because the writer itself is still healthy - the caller supplied too
+        // much work, not the system asking for teardown - and consumers who care about the distinction can `instanceof`-check rather than match on message text.
+        if ((this.#highWaterMark !== undefined) && (this.#queue.length >= this.#highWaterMark)) {
+            throw new BackpressureOverflowError();
+        }
+        const resolvers = Promise.withResolvers();
+        this.#queue.push({ chunk, resolvers });
+        // Spin up the drain loop when nothing is already processing. We key off the `#processing` flag rather than `#drainTask` because an async function's body runs
+        // synchronously until its first `await`: a no-backpressure drain completes before `write()` returns, leaving `#drainTask` set to a resolved-but-not-yet-cleared
+        // promise that would falsely gate subsequent writes. `#processing` is flipped true at the top of `#drain` and false in its `finally`, so checking it gives us a
+        // truthful "is a drain currently running?" answer with no chained-promise races.
+        if (!this.#processing) {
+            this.#drainTask = this.#drain();
+        }
+        return resolvers.promise;
+    }
+    /**
+     * Abort the writer and tear it down. Defaults to `HbpuAbortError("shutdown")` when no reason is supplied; explicit reasons pass through unchanged.
+     *
+     * Safe to call more than once: subsequent calls are no-ops because the underlying signal only aborts once. Every queued write rejects with the signal's reason; any
+     * in-flight drain wait rejects with the signal's reason as well, and that rejection propagates out of the in-flight `write()` promise.
+     *
+     * @param reason - Optional abort reason. Typically an {@link HbpuAbortError}; platform errors (`TimeoutError`, `AbortError`) also interoperate by convention.
      */
-    write(data) {
-        // If the writer has been closed or the stream is unavailable or not writable, reject the write.
-        const stream = this.isClosed ? null : this.getStream();
-        if (!stream?.writable) {
-            return false;
+    abort(reason) {
+        if (this.aborted) {
+            return;
         }
-        // Add the data to the queue and process it.
-        this.queue.push(data);
-        this.processQueue();
-        return true;
+        this.#controller.abort(reason ?? new HbpuAbortError("shutdown"));
     }
     /**
-     * Closes the writer, clearing any pending data and removing drain listeners. After closing, all subsequent writes are rejected. This should be called when the
-     * underlying stream is being shut down or the session is ending.
+     * `AsyncDisposable` implementation. Aborts the writer (defaulting to `"shutdown"`) and awaits actual drain-loop completion before returning, so callers using
+     * `await using` are guaranteed every pending write has settled by the time the surrounding scope exits.
+     *
+     * @returns A promise that resolves once the drain loop has fully exited.
      */
-    close() {
-        this.isClosed = true;
-        this.isWriting = false;
-        this.queue.length = 0;
-        // Remove any pending drain listener.
-        if (this.drainListener && this.drainStream) {
-            this.drainStream.off("drain", this.drainListener);
-            this.drainListener = null;
-            this.drainStream = null;
+    async [Symbol.asyncDispose]() {
+        this.abort();
+        if (this.#drainTask) {
+            // Drain failures are already observed through the individual write promises; swallow here so `await using` does not surface cleanup-side errors the caller has
+            // no way to react to.
+            await this.#drainTask.catch(() => { });
         }
     }
     /**
-     * Returns the number of segments currently queued and waiting to be written.
+     * `true` once `this.signal` has aborted. Derived from the signal; no independent state.
+     */
+    get aborted() {
+        return this.signal.aborted;
+    }
+    /**
+     * Total number of entries in the pending-write queue, including the in-flight entry (if the drain loop is parked on `events.once(stream, "drain", { signal })`).
+     * Matches the depth that the configured `highWaterMark` is compared against, so adaptive producers watching this value see the same accounting the writer uses
+     * internally.
      */
     get pending() {
-        return this.queue.length;
+        return this.#queue.length;
     }
-    // Process the write queue. Dequeues segments and writes them to the stream, respecting backpressure by waiting for drain events before continuing. The synchronous
-    // success path uses a loop rather than recursion to avoid growing the call stack when processing a burst of queued segments (e.g., initial timeshift buffer flush).
-    processQueue() {
-        // If we already have a write in progress, we're done...the drain listener will resume processing.
-        if (this.isWriting) {
-            return;
-        }
-        // Process as many queued segments as the stream can accept without backpressure.
-        while (this.queue.length) {
-            // Resolve the stream. If it's gone or no longer writable, we can't write.
-            const stream = this.isClosed ? null : this.getStream();
-            if (!stream?.writable) {
-                return;
-            }
-            // Dequeue and write.
-            this.isWriting = true;
-            const segment = this.queue.shift();
-            if (!stream.write(segment)) {
-                // The stream signaled backpressure. Wait for drain before processing the next segment.
-                this.drainStream = stream;
-                this.drainListener = () => {
-                    this.drainStream = null;
-                    this.drainListener = null;
-                    this.isWriting = false;
-                    this.onWrite?.();
-                    this.processQueue();
-                };
-                stream.once("drain", this.drainListener);
-                return;
+    // Drain loop. Iterates the queue, writing each chunk through the provider's current stream, honoring backpressure via `events.once(stream, "drain", { signal })`.
+    // Runs until the queue is empty or the signal aborts; every in-flight write is settled before exit (resolved on successful write, rejected via drain-abort on
+    // teardown). Note the peek-then-shift pattern: the entry stays at `queue[0]` while the write is in flight, so `queue.length` reflects the true pending count
+    // (including the in-flight entry) and `highWaterMark` checks in `write()` work uniformly whether the drain is idle or mid-wait.
+    async #drain() {
+        this.#processing = true;
+        try {
+            while ((this.#queue.length > 0) && !this.signal.aborted) {
+                const entry = this.#queue[0];
+                // `length`-guarded peek: the loop condition just checked non-empty, so we always have an entry. `noUncheckedIndexedAccess` widens the indexed access to
+                // `PendingWrite | undefined`; the null check below narrows for the compiler without changing runtime semantics.
+                if (!entry) {
+                    break;
+                }
+                // Re-evaluate the stream on every iteration. The provider is free to return a different instance across turns (stream replacement across restarts) or `null`
+                // (no live stream right now - drop the chunk). Both cases are expected in HBUP's pipeline and are handled here without surfacing as errors to the caller.
+                const stream = this.#streamProvider();
+                if (!stream) {
+                    // Drop semantics: the provider explicitly said "no stream." The write promise resolves so the caller can continue without branching on a per-write return;
+                    // the surrounding session is responsible for deciding whether the lack of a stream is itself a fault.
+                    this.#queue.shift();
+                    entry.resolvers.resolve();
+                    continue;
+                }
+                if (!stream.writable) {
+                    // Stream exists but has ended. Reject this specific write with a {@link BackpressureClosedStreamError} and let the caller decide whether to escalate - we
+                    // do not abort the writer here, because a later stream replacement (via the provider) may revive the pipeline.
+                    this.#queue.shift();
+                    entry.resolvers.reject(new BackpressureClosedStreamError());
+                    continue;
+                }
+                try {
+                    // `stream.write()` returns `false` when the high-water mark has been breached; the write is still queued by Node, but we must wait for `drain` before
+                    // pushing more bytes or we risk unbounded growth of Node's internal write buffer in process memory. `events.once` with `{ signal }` ties the wait to the
+                    // writer's lifetime so an abort during drain rejects the wait with the signal's reason rather than hanging.
+                    if (!stream.write(entry.chunk)) {
+                        // eslint-disable-next-line no-await-in-loop
+                        await once(stream, "drain", { signal: this.signal });
+                    }
+                    this.#queue.shift();
+                    entry.resolvers.resolve();
+                }
+                catch (error) {
+                    // Two rejection shapes land here. (a) Our signal aborted mid-drain: `once` rejects with `signal.reason`; we surface that to the caller and exit the loop
+                    // because teardown is already in flight. (b) The stream emitted an error via some path `events.once` exposes: the write that triggered the error cannot
+                    // complete, so we reject this caller and abort the writer with `"failed"` so no subsequent write tries to reuse a broken stream silently.
+                    this.#queue.shift();
+                    if (this.aborted) {
+                        entry.resolvers.reject(this.signal.reason);
+                        return;
+                    }
+                    entry.resolvers.reject(error);
+                    this.#controller.abort(new HbpuAbortError("failed", { cause: error }));
+                    return;
+                }
             }
-            // Write succeeded immediately. Notify the caller and continue to the next segment.
-            this.isWriting = false;
-            this.onWrite?.();
+        }
+        finally {
+            this.#processing = false;
+        }
+    }
+    // Teardown convergence point, fired exactly once when `this.signal` aborts. Rejects every pending entry with the signal's reason, regardless of whether the drain
+    // loop is currently processing. Promise resolvers are inert after first settlement, so if the drain loop's catch branch also rejects the in-flight resolver
+    // (e.g., when `events.once(..., { signal })` rejects on the same abort), the second call is a no-op. Draining the queue unconditionally here prevents the
+    // stream-error escalation path from orphaning queued resolvers - `#drain`'s catch shifts the in-flight entry and then calls `this.#controller.abort(...)`, which
+    // fires this listener synchronously while the remaining queued entries are still in the queue.
+    #teardown() {
+        // `signal.reason` is typed `any` in the DOM lib. The `: unknown` annotation narrows it to `unknown` for the `@typescript-eslint/no-unsafe-assignment` rule, which
+        // surfaces stray `any` values on assignment. `unknown` flows through `resolvers.reject()` unchanged - reject accepts any value.
+        const reason = this.signal.reason;
+        const pending = this.#queue.splice(0);
+        for (const entry of pending) {
+            entry.resolvers.reject(reason);
         }
     }
 }

package/dist/backpressure.js.map

@@ -1 +1 @@
-{"version":3,"file":"backpressure.js","sourceRoot":"","sources":["../src/backpressure.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backpressure.js","sourceRoot":"","sources":["../src/backpressure.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAEzB,IAAI,GAAG,2BAAoC,CAAC;IAErE,YAAmB,OAAO,GAAG,mEAAmE;QAE9F,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IAE7B,IAAI,GAAG,+BAAwC,CAAC;IAEzE,YAAmB,OAAO,GAAG,wDAAwD;QAEnF,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AA4BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,kBAAkB;IAE7B;;;OAGG;IACa,MAAM,CAAc;IAEpC,mKAAmK;IACnK,iHAAiH;IACxG,WAAW,CAAkB;IAEtC,qKAAqK;IACrK,oBAAoB;IACX,cAAc,CAAqB;IAE5C,mKAAmK;IACnK,yGAAyG;IAChG,eAAe,CAA2B;IAEnD,kKAAkK;IAClK,gKAAgK;IAChK,wCAAwC;IAC/B,MAAM,GAAmB,EAAE,CAAC;IAErC,kKAAkK;IAClK,iFAAiF;IACjF,UAAU,CAA4B;IAEtC,iKAAiK;IACjK,mKAAmK;IACnK,+JAA+J;IAC/J,WAAW,GAAG,KAAK,CAAC;IAEpB;;;;;;;;;;;OAWG;IACH,YAAmB,cAAwC,EAAE,OAA+B,EAAE;QAE5F,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;QACtC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,aAAa,CAAC;QAEzC,IAAI,CAAC,WAAW,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAEnE,6JAA6J;QAC7J,iIAAiI;QACjI,+JAA+J;QAC/J,oJAAoJ;QACpJ,+JAA+J;QAC/J,sFAAsF;QACtF,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACI,KAAK,CAAC,KAAK,CAAC,KAAa;QAE9B,8JAA8J;QAC9J,iGAAiG;QACjG,IAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAEvB,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAC3B,CAAC;QAED,0JAA0J;QAC1J,kKAAkK;QAClK,yJAAyJ;QACzJ,IAAG,CAAC,IAAI,CAAC,cAAc,KAAK,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;YAEtF,MAAM,IAAI,yBAAyB,EAAE,CAAC;QACxC,CAAC;QAED,MAAM,SAAS,GAA+B,OAAO,CAAC,aAAa,EAAE,CAAC;QAEtE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAEvC,8JAA8J;QAC9J,gKAAgK;QAChK,gKAAgK;QAChK,iFAAiF;QACjF,IAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAErB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAClC,CAAC;QAED,OAAO,SAAS,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,MAAgB;QAE3B,IAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YAEhB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;IACnE,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;QAEhC,IAAI,CAAC,KAAK,EAAE,CAAC;QAEb,IAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAEnB,+JAA+J;YAC/J,sBAAsB;YACtB,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,GAAmC,CAAC,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAW,OAAO;QAEhB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,IAAW,OAAO;QAEhB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,kKAAkK;IAClK,8JAA8J;IAC9J,6JAA6J;IAC7J,gIAAgI;IAChI,KAAK,CAAC,MAAM;QAEV,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAExB,IAAI,CAAC;YAEH,OAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAEvD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAE7B,wJAAwJ;gBACxJ,gHAAgH;gBAChH,IAAG,CAAC,KAAK,EAAE,CAAC;oBAEV,MAAM;gBACR,CAAC;gBAED,6JAA6J;gBAC7J,0JAA0J;gBAC1J,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;gBAEtC,IAAG,CAAC,MAAM,EAAE,CAAC;oBAEX,2JAA2J;oBAC3J,sGAAsG;oBACtG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;oBACpB,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;oBAE1B,SAAS;gBACX,CAAC;gBAED,IAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;oBAEpB,0JAA0J;oBAC1J,+GAA+G;oBAC/G,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;oBACpB,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,6BAA6B,EAAE,CAAC,CAAC;oBAE5D,SAAS;gBACX,CAAC;gBAED,IAAI,CAAC;oBAEH,sJAAsJ;oBACtJ,yJAAyJ;oBACzJ,4GAA4G;oBAC5G,IAAG,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;wBAE9B,4CAA4C;wBAC5C,MAAM,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;oBACvD,CAAC;oBAED,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;oBACpB,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;gBAC5B,CAAC;gBAAC,OAAM,KAAc,EAAE,CAAC;oBAEvB,yJAAyJ;oBACzJ,wJAAwJ;oBACxJ,0IAA0I;oBAC1I,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;oBAEpB,IAAG,IAAI,CAAC,OAAO,EAAE,CAAC;wBAEhB,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;wBAE3C,OAAO;oBACT,CAAC;oBAED,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBAC9B,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;oBAEvE,OAAO;gBACT,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YAET,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,kKAAkK;IAClK,4JAA4J;IAC5J,0JAA0J;IAC1J,iKAAiK;IACjK,+FAA+F;IAC/F,SAAS;QAEP,kKAAkK;QAClK,gIAAgI;QAChI,MAAM,MAAM,GAAY,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAEtC,KAAI,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAE3B,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;CACF"}

package/dist/cli/index.d.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * The homebridge-plugin-utils CLI, exposed to consumers via the `bin` field in `package.json`. A single cohesive module: the content-hash helper, the `prepareUi`,
+ * `prepareDocs`, and `prepareChrome` transforms, the `runCli` dispatcher, and the entry-point execution all live here with no inter-file relative VALUE imports.
+ *
+ * That single-file shape is deliberate, not incidental. A bin is invoked through an `npm`-managed symlink in `node_modules/.bin`; if the entry imported a sibling
+ * module by relative path AT LOAD TIME, that import would resolve against the symlink's directory under symlink-preserving or copied-package layouts and fail. With
+ * every runtime edge pointing only at `node:` builtins, there is nothing to fracture - the CLI runs identically whether reached directly, through a symlink, through
+ * a `file:` dependency, or under `--preserve-symlinks`. The lone `import type` of the renderer's signatures is fully erased by the compiler and emits no runtime edge,
+ * so it carries the SSOT types without reintroducing a load-time relative dependency; when `prepareDocs` actually needs the renderer it reaches it through a computed
+ * dynamic import the dispatch site supplies, the same indirection the `hblog` bin uses.
+ *
+ * The module is simultaneously the executable (run via the bin) and a side-effect-free library surface (`prepareUi` / `prepareDocs` / `prepareChrome` / `runCli` /
+ * `USAGE`) that the test suite imports. The entry block at the bottom only executes when this module is the program entry point, detected by comparing canonicalized
+ * real paths - see its comment for why a raw path comparison is insufficient.
+ *
+ * @module
+ */
+import type { parseDocChromeManifest, parseProjectEntries, renderDevBadges, renderDocIndex, renderMasthead, renderProjects } from "../docChrome.ts";
+import type { renderFeatureOptionsReference, spliceMarkedRegion } from "../featureOptions-docs.ts";
+/**
+ * Usage banner shown on no command or an unknown command. Kept as an exported constant so tests assert against its text without
+ * coupling to formatting details and so README documentation can reference it via import rather than duplicate.
+ */
+export declare const USAGE: string;
+/**
+ * Mirror HBPU's compiled browser-side webUI into a plugin's homebridge-ui/public/lib directory under a content-hashed, version-named subdirectory. The subdir name
+ * combines the package's semver version with a short content hash of `dist/ui/` (e.g., `2.0.0-abc1234567890def`), so the browser's HTTP cache invalidates
+ * structurally on any content change rather than via per-file query-string hacks: the plugin's `index.html` reads the small manifest written alongside, then
+ * injects a trailing-slash importmap entry that prefixes every `./lib/` import with the hashed-versioned path. Transitive imports inherit the prefix through
+ * relative-URL resolution, so cache-busting reaches files the importmap never names.
+ *
+ * The content hash is what makes the maintainer-iteration use case work. A semver-only subdir name would stay constant across the maintainer's
+ * edit/rebuild/test cycle (version doesn't bump on every save), and the browser would happily serve cached copies of the stale URLs. Hashing the tree means any
+ * source change produces a different subdir name, which produces different URLs, which forces fresh fetches. Same code path serves the published-release case: a
+ * release ships with a fixed hash, and every consumer fetching it sees the same URL space and caches aggressively within it.
+ *
+ * Operates repeatably. A re-run against unchanged source content produces the same subdir name + same contents + same manifest. Stale prior-build subdirs are
+ * removed in the same pass; non-version-shaped entries in the destination are left untouched so a plugin's own files (assets, sibling tooling, README copies)
+ * survive across runs.
+ *
+ * @param args
+ * @param args.dest       - The plugin's destination directory (typically `homebridge-ui/public/lib`). Created if missing.
+ * @param args.sourceRoot - Path to HBPU's package root (the directory containing `package.json` and `dist/`). The entry block resolves this from the CLI's own
+ *                          real path; tests pass a tmpdir populated with a synthetic HBPU layout.
+ *
+ * @throws When the source has not been built (`dist/ui/` missing), the source `package.json` lacks a `version` field, or the source `dist/ui` path exists but is not a
+ *         directory.
+ */
+export declare function prepareUi({ dest, sourceRoot }: {
+    dest: string;
+    sourceRoot: string;
+}): Promise<void>;
+/**
+ * Regenerate a plugin's Feature Options reference by projecting its live catalog through HBPU's shared renderer and splicing the result into the plugin's doc, in
+ * place between the shared `FEATURE OPTIONS:BEGIN` / `END` markers. This centralizes the read/splice/atomic-write orchestration so a plugin's `build-docs` script
+ * only needs a single line invoking this subcommand instead of a bespoke `*-gendocs.ts` shim.
+ *
+ * Pure-by-injection on `render` and `splice`: the renderer and the splice helper are passed in rather than imported statically, so this function is unit-testable
+ * against the real `featureOptions-docs.ts` exports without a built `dist/`, and the CLI's single-file no-static-relative-import discipline is preserved (the dispatch
+ * site reaches the renderer through a computed dynamic import). The catalog is loaded by dynamic import of its absolute path resolved to a `file:` URL, since a bare
+ * absolute path is not a valid ESM specifier on every platform. The module's required exports are validated up front so a mis-shaped catalog fails with a
+ * diagnostic naming the offending module and export rather than a downstream type error inside the renderer.
+ *
+ * The same catalog module may OPTIONALLY export scope hooks - `describeCategoryScope` and `describeOptionScope` - that the renderer threads through to contribute
+ * plugin-private scope prose (a device-scope line under a category heading, a suffix on an option's description cell). These are the annotated-plugin extension point
+ * (Protect/Access); a zero-config plugin (ratgdo) exports neither and documents every option unconditionally. Each hook is validated INDEPENDENTLY: if a module exports
+ * one under either name it MUST be a function, else this throws a framed diagnostic naming the module and the offending export; an absent hook is simply omitted, and
+ * the renderer already treats an absent hook as "omit cleanly". Because the hooks arrive through the dynamic-imported catalog namespace (never a static relative
+ * import), they preserve the bin's symlink-safe load-time edge discipline exactly as the catalog arrays do.
+ *
+ * The write is atomic: the new contents are staged in a sibling `.tmp` file and renamed over the doc. The rename is atomic on a single filesystem, so a crash
+ * mid-write can never leave a half-spliced doc behind - the file is either the prior content or the complete new content, never a truncated splice.
+ *
+ * @param args
+ * @param args.catalogModulePath - Absolute path to the plugin's compiled catalog module exporting `featureOptionCategories` (an array) and `featureOptions` (an
+ *                                 object). Resolved to a `file:` URL before the dynamic import.
+ * @param args.docPath           - Absolute path to the doc whose marked region is replaced (typically the plugin's `docs/FeatureOptions.md`).
+ * @param args.render            - The injected {@link renderFeatureOptionsReference} from `featureOptions-docs.ts`.
+ * @param args.splice            - The injected {@link spliceMarkedRegion} from `featureOptions-docs.ts`.
+ *
+ * @throws When the catalog module lacks `featureOptionCategories` (or it is not an array) or `featureOptions` (or it is not a non-null object), when it exports a
+ *         present-but-non-function `describeCategoryScope` or `describeOptionScope`, and propagates the splice's own framed errors when the doc's marker pair is absent
+ *         or ambiguous.
+ */
+export declare function prepareDocs({ catalogModulePath, docPath, render, splice }: {
+    catalogModulePath: string;
+    docPath: string;
+    render: typeof renderFeatureOptionsReference;
+    splice: typeof spliceMarkedRegion;
+}): Promise<void>;
+interface DocChromeModule {
+    readonly DEV_BADGES_BEGIN: string;
+    readonly DEV_BADGES_END: string;
+    readonly DOCUMENTATION_BEGIN: string;
+    readonly DOCUMENTATION_END: string;
+    readonly MASTHEAD_BEGIN: string;
+    readonly MASTHEAD_END: string;
+    readonly PROJECTS_BEGIN: string;
+    readonly PROJECTS_END: string;
+    readonly parseDocChromeManifest: typeof parseDocChromeManifest;
+    readonly parseProjectEntries: typeof parseProjectEntries;
+    readonly renderDevBadges: typeof renderDevBadges;
+    readonly renderDocIndex: typeof renderDocIndex;
+    readonly renderMasthead: typeof renderMasthead;
+    readonly renderProjects: typeof renderProjects;
+}
+/**
+ * Stamp a plugin's documentation-chrome regions - the masthead, the documentation index, the dashboard badges, and the project list - across its README, every content
+ * doc, and its webUI Support tab, from one per-plugin manifest. This is the multi-region, multi-file counterpart to {@link prepareDocs}: where that regenerates one
+ * feature-options region in one doc, this regenerates several named regions in many files, so a plugin's masthead and navigation cannot drift between the surfaces that
+ * repeat them.
+ *
+ * Pure-by-injection like {@link prepareDocs}: the `docChrome` renderers and validator arrive through the injected `chrome` namespace and the splice helper through
+ * `splice`, so this function is unit-testable against the real exports without a built `dist/`, and the CLI's single-file no-static-relative-import discipline is
+ * preserved. `fetchImpl` is injected (defaulting to the global `fetch`) so the remote project-source path is testable without network access.
+ *
+ * The manifest is loaded (a typed module or a static JSON file), validated with a field-naming diagnostic, and its optional project source resolved to inline data. The
+ * per-file edit plan is then built - the README carries the masthead, the documentation index, and the dashboard badges; each content doc carries the masthead (unless
+ * its entry opts out) and a self-omitting footer index; the webUI, when present, carries the documentation index and the project list. Every region is spliced against
+ * its own marker pair through the shared, ambiguity-rejecting splice primitive.
+ *
+ * The write is all-or-nothing across files in the realistic failure mode. Splicing happens entirely in memory first, so a missing or ambiguous marker in any file
+ * aborts the run before a single write. The writes then proceed in two phases - every file's new content is staged in a sibling `.tmp`, and only once all temps exist
+ * are they renamed over their targets - so a staging failure leaves every original untouched and each promotion is an atomic rename.
+ *
+ * @param args
+ * @param args.chrome       - The injected `docChrome` module namespace (its renderers, marker constants, and validators).
+ * @param args.fetchImpl    - The `fetch` implementation used to resolve a remote project source. Defaults to the global `fetch`; tests inject a fake.
+ * @param args.manifestPath - Absolute path to the plugin's manifest - a compiled module or a `.json` file.
+ * @param args.pluginRoot   - Absolute path to the plugin root that the manifest's surface and file references resolve against.
+ * @param args.splice       - The injected {@link spliceMarkedRegion} from `featureOptions-docs.ts`.
+ *
+ * @throws When the manifest is mis-shaped, when a resolved project source is malformed, when a target file cannot be read, or when any region's marker pair is absent or
+ *         ambiguous - propagating the splice's own framed errors so the dispatch site frames them uniformly.
+ */
+export declare function prepareChrome({ chrome, fetchImpl, manifestPath, pluginRoot, splice }: {
+    chrome: DocChromeModule;
+    fetchImpl?: typeof fetch;
+    manifestPath: string;
+    pluginRoot: string;
+    splice: typeof spliceMarkedRegion;
+}): Promise<void>;
+/**
+ * Run the CLI against a synthetic argv vector. Returns the process exit code that the entry block propagates. Pure-by-injection: takes its `cwd`, `stderr`, and
+ * `sourceRoot` as arguments rather than reading them from globals, so tests exercise the full dispatch path against a captured stderr, a tmpdir source root, and a
+ * tmpdir working directory without ever touching `process.exit` or the real filesystem outside the tmpdir scope.
+ *
+ * @param args
+ * @param args.argv       - Positional and flag arguments (typically `process.argv.slice(2)`).
+ * @param args.cwd        - The working directory that relative subcommand path arguments resolve against. Production passes `process.cwd()`; tests pass a tmpdir.
+ * @param args.sourceRoot - Path to HBPU's package root (resolved from the CLI's real path by the entry block; tests pass a tmpdir).
+ * @param args.stderr     - Stream-like sink for usage and error output. Production passes `process.stderr`; tests pass a captured-output collector.
+ *
+ * @returns The exit code: `0` on success or on an explicit no-arg invocation showing the usage banner, `1` on misuse or subcommand failure.
+ */
+export declare function runCli({ argv, cwd, sourceRoot, stderr }: {
+    argv: readonly string[];
+    cwd: string;
+    sourceRoot: string;
+    stderr: {
+        write: (chunk: string) => unknown;
+    };
+}): Promise<number>;
+export {};
+//# sourceMappingURL=index.d.ts.map