homebridge-plugin-utils 2.0.0 → 2.1.0

package/dist/disposable-stack.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A container that aggregates disposable resources and disposes them, in reverse (last-in-first-out) order, when the stack itself is disposed.
+ *
+ * The class satisfies the platform `DisposableStack` interface by construction - the `implements` clause below binds it to `globalThis.DisposableStack`, so the
+ * compiler enforces that the name's promise (the platform contract) is kept at the definition site.
+ *
+ * @category Utilities
+ */
+export declare class DisposableStack implements InstanceType<typeof globalThis.DisposableStack> {
+    #private;
+    readonly [Symbol.toStringTag] = "DisposableStack";
+    /**
+     * Whether this stack has been disposed.
+     */
+    get disposed(): boolean;
+    /**
+     * Register a {@link Disposable} whose `[Symbol.dispose]()` runs when this stack is disposed, returning the value unchanged.
+     *
+     * `null` and `undefined` pass through without being registered. The dispose method is captured at registration time and invoked with the value as its receiver, so
+     * a later mutation of `value[Symbol.dispose]` cannot change what runs.
+     *
+     * @param value - The resource to register, or `null`/`undefined` to skip registration.
+     * @returns The provided `value`.
+     */
+    use<T extends Disposable | null | undefined>(value: T): T;
+    /**
+     * Register a value together with an explicit disposal callback, returning the value unchanged. The callback is invoked with the value as its first argument when
+     * this stack is disposed.
+     *
+     * @param value - The value to associate with the callback.
+     * @param onDispose - The disposal callback, invoked with `value`.
+     * @returns The provided `value`.
+     */
+    adopt<T>(value: T, onDispose: (value: T) => void): T;
+    /**
+     * Register a callback to run when this stack is disposed.
+     *
+     * @param onDispose - The callback to run on disposal.
+     */
+    defer(onDispose: () => void): void;
+    /**
+     * Move every pending disposer out of this stack into a fresh {@link DisposableStack}, preserving registration order, and mark this stack disposed without running
+     * anything. This is the "commit" primitive: after a successful acquire sequence, moving the disposers away disarms this stack's scope-bound cleanup while handing
+     * responsibility for those resources to the returned stack.
+     *
+     * @returns A new stack owning the transferred disposers.
+     */
+    move(): DisposableStack;
+    /**
+     * Dispose every registered resource in reverse (last-in-first-out) order. A second call is a no-op. Every disposer runs even when an earlier one throws: a single
+     * failure is rethrown after the sweep completes, and multiple failures chain through `SuppressedError` (the newest failure wrapping the accumulated one).
+     */
+    dispose(): void;
+    /**
+     * Dispose this stack. Enables `using` semantics by delegating to {@link dispose}.
+     */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=disposable-stack.d.ts.map

package/dist/disposable-stack.js

@@ -0,0 +1,155 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * disposable-stack.ts: An in-package stand-in for the platform `DisposableStack` global that the library's own port allocator relies on.
+ */
+// Build a `SuppressedError` that links a newer disposal failure to the error it supersedes, matching the spec's multi-failure aggregation shape. We read the platform
+// `SuppressedError` global fresh on every call rather than caching a reference, because that constructor is itself part of the Node 24 explicit-resource-management
+// surface and can be absent on the engines floor this module exists to serve. When it is missing we synthesize a structurally-identical stand-in - an `Error` whose
+// name is "SuppressedError" carrying `error` and `suppressed` - so multi-failure aggregation is observably identical whether or not the global is present. The typed
+// optional read tells the truth the platform lib cannot: on this engines floor the global may not exist.
+function createSuppressedError(error, suppressed) {
+    const suppressedErrorConstructor = globalThis.SuppressedError;
+    if (suppressedErrorConstructor !== undefined) {
+        return new suppressedErrorConstructor(error, suppressed);
+    }
+    const synthesized = new Error();
+    synthesized.error = error;
+    synthesized.name = "SuppressedError";
+    synthesized.suppressed = suppressed;
+    return synthesized;
+}
+/**
+ * A container that aggregates disposable resources and disposes them, in reverse (last-in-first-out) order, when the stack itself is disposed.
+ *
+ * The class satisfies the platform `DisposableStack` interface by construction - the `implements` clause below binds it to `globalThis.DisposableStack`, so the
+ * compiler enforces that the name's promise (the platform contract) is kept at the definition site.
+ *
+ * @category Utilities
+ */
+export class DisposableStack {
+    // The pending disposers in registration order. A `null` array is the disposed state: pairing "disposed" with "no pending disposers" in a single field makes the
+    // disposed-with-pending-work state unrepresentable, so every member checks this one field to decide whether it may still register or run work.
+    #disposers = [];
+    // The platform tag reported by `Object.prototype.toString`, matching the native class.
+    [Symbol.toStringTag] = "DisposableStack";
+    /**
+     * Whether this stack has been disposed.
+     */
+    get disposed() {
+        return this.#disposers === null;
+    }
+    /**
+     * Register a {@link Disposable} whose `[Symbol.dispose]()` runs when this stack is disposed, returning the value unchanged.
+     *
+     * `null` and `undefined` pass through without being registered. The dispose method is captured at registration time and invoked with the value as its receiver, so
+     * a later mutation of `value[Symbol.dispose]` cannot change what runs.
+     *
+     * @param value - The resource to register, or `null`/`undefined` to skip registration.
+     * @returns The provided `value`.
+     */
+    use(value) {
+        if (this.#disposers === null) {
+            throw new ReferenceError("Cannot use a resource on a disposed DisposableStack.");
+        }
+        // Skip registration for null and undefined, returning them unchanged. We test undefined with `typeof` so the generic parameter narrows cleanly to a Disposable for
+        // the member access below.
+        if ((value === null) || (typeof value === "undefined")) {
+            return value;
+        }
+        // Capture the dispose method now, at registration time, matching the spec's registration-time capture... a later mutation of `value[Symbol.dispose]` must not change
+        // what runs. We read it through `unknown` because use() is a trust boundary: a value can satisfy the Disposable type nominally yet present a non-callable member at
+        // runtime, which the spec requires we reject with a TypeError.
+        const disposeMethod = value[Symbol.dispose];
+        if (typeof disposeMethod !== "function") {
+            throw new TypeError("The value passed to DisposableStack.use() is not disposable.");
+        }
+        const boundDispose = disposeMethod;
+        this.#disposers.push(() => {
+            boundDispose.call(value);
+        });
+        return value;
+    }
+    /**
+     * Register a value together with an explicit disposal callback, returning the value unchanged. The callback is invoked with the value as its first argument when
+     * this stack is disposed.
+     *
+     * @param value - The value to associate with the callback.
+     * @param onDispose - The disposal callback, invoked with `value`.
+     * @returns The provided `value`.
+     */
+    adopt(value, onDispose) {
+        if (this.#disposers === null) {
+            throw new ReferenceError("Cannot adopt a resource on a disposed DisposableStack.");
+        }
+        if (typeof onDispose !== "function") {
+            throw new TypeError("The onDispose callback passed to DisposableStack.adopt() is not a function.");
+        }
+        this.#disposers.push(() => onDispose(value));
+        return value;
+    }
+    /**
+     * Register a callback to run when this stack is disposed.
+     *
+     * @param onDispose - The callback to run on disposal.
+     */
+    defer(onDispose) {
+        if (this.#disposers === null) {
+            throw new ReferenceError("Cannot defer a callback on a disposed DisposableStack.");
+        }
+        if (typeof onDispose !== "function") {
+            throw new TypeError("The onDispose callback passed to DisposableStack.defer() is not a function.");
+        }
+        this.#disposers.push(onDispose);
+    }
+    /**
+     * Move every pending disposer out of this stack into a fresh {@link DisposableStack}, preserving registration order, and mark this stack disposed without running
+     * anything. This is the "commit" primitive: after a successful acquire sequence, moving the disposers away disarms this stack's scope-bound cleanup while handing
+     * responsibility for those resources to the returned stack.
+     *
+     * @returns A new stack owning the transferred disposers.
+     */
+    move() {
+        if (this.#disposers === null) {
+            throw new ReferenceError("Cannot move a disposed DisposableStack.");
+        }
+        const moved = new DisposableStack();
+        // Transfer the array by reference so order is preserved, then mark this stack disposed without running any disposer.
+        moved.#disposers = this.#disposers;
+        this.#disposers = null;
+        return moved;
+    }
+    /**
+     * Dispose every registered resource in reverse (last-in-first-out) order. A second call is a no-op. Every disposer runs even when an earlier one throws: a single
+     * failure is rethrown after the sweep completes, and multiple failures chain through `SuppressedError` (the newest failure wrapping the accumulated one).
+     */
+    dispose() {
+        if (this.#disposers === null) {
+            return;
+        }
+        // Detach the array and mark disposed before running anything, so a disposer that re-enters this stack observes the disposed state and cannot double-run work.
+        const disposers = this.#disposers;
+        this.#disposers = null;
+        let hasError = false;
+        let heldError;
+        // Reverse the detached array in place - we hold the only reference to it, so mutating it is safe - and run the disposers last-in-first-out.
+        for (const disposer of disposers.reverse()) {
+            try {
+                disposer();
+            }
+            catch (error) {
+                heldError = hasError ? createSuppressedError(error, heldError) : error;
+                hasError = true;
+            }
+        }
+        if (hasError) {
+            throw heldError;
+        }
+    }
+    /**
+     * Dispose this stack. Enables `using` semantics by delegating to {@link dispose}.
+     */
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+}
+//# sourceMappingURL=disposable-stack.js.map

package/dist/disposable-stack.js.map

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

package/dist/docChrome.d.ts

@@ -0,0 +1,260 @@
+/**
+ * A shared documentation-chrome renderer for the family's plugins.
+ *
+ * Every plugin hand-maintains the same "chrome" in many places: a multi-line badge/logo masthead byte-copied to the top of the README and every content doc, and an
+ * ordered documentation index (each doc's title plus a one-line blurb) duplicated between the README's documentation section and the webUI's Support tab. Those copies
+ * drift - a badge label here, a blurb there, an href form that differs per surface. This module collapses all of it into one per-plugin {@link DocChromeManifest} that a
+ * plugin authors once (as a typed module or a static JSON file), so each surface becomes a pure projection of a single source of truth.
+ *
+ * The module exports pure string renderers - {@link renderMasthead}, {@link renderDocIndex}, {@link renderDevBadges}, {@link renderProjects} - and the marker constants
+ * each surface embeds, plus the {@link parseDocChromeManifest} / {@link parseProjectEntries} validators. Like `featureOptions-docs.ts`, every function here is pure and
+ * isomorphic: no `node:` imports, no `fs`, no `fetch`. Reading the target files, resolving a remote project list, and writing the spliced result back are the CLI's
+ * concern; this module only ever renders already-resolved data. That keeps it browser-safe and trivially testable, though it is a tooling concern and is deliberately
+ * NOT mirrored into `dist/ui/`.
+ *
+ * @module
+ */
+/**
+ * Repository coordinates used to derive the GitHub blob URLs that navigation entries link to. The blob base is `https://github.com/{owner}/{name}/blob/{branch}`.
+ *
+ * @category Doc Chrome
+ */
+export interface RepoCoordinates {
+    readonly branch: string;
+    readonly name: string;
+    readonly owner: string;
+}
+/**
+ * A single shields-style badge: its alt text, its image URL, and the URL it links to. Stored as a full image URL rather than assembled from parts so the manifest stays
+ * provider-agnostic - any badge service works, not just shields.io.
+ *
+ * @category Doc Chrome
+ */
+export interface Badge {
+    readonly alt: string;
+    readonly image: string;
+    readonly link: string;
+}
+/**
+ * The masthead: the centered logo, the H1 title, the ordered badge row, and the H2 tagline. Rendered identically into the README and every content doc. Text fields are
+ * author-owned markup (the tagline may contain markdown links) and pass through verbatim.
+ *
+ * @category Doc Chrome
+ */
+export interface Masthead {
+    readonly badges: readonly Badge[];
+    readonly logo: {
+        readonly alt: string;
+        readonly href: string;
+        readonly src: string;
+    };
+    readonly tagline: string;
+    readonly title: string;
+}
+/**
+ * One documentation-index entry. A discriminated union on `kind`: a `"doc"` entry points at a file under the plugin's `docs/` tree (and may opt out of the masthead via
+ * `masthead: false`, as the changelog does), while a `"readme-anchor"` entry points at a section anchor within the README itself. The renderer derives the correct href
+ * per surface from this one canonical shape, so the same entry can render as an in-README anchor on the README and as an absolute blob URL everywhere else.
+ *
+ * @category Doc Chrome
+ */
+export type DocEntry = {
+    readonly anchor: string;
+    readonly blurb: string;
+    readonly kind: "readme-anchor";
+    readonly title: string;
+} | {
+    readonly blurb: string;
+    readonly file: string;
+    readonly kind: "doc";
+    readonly masthead?: boolean;
+    readonly title: string;
+};
+/**
+ * A named, ordered group of documentation entries (for example "Getting Started" or "Additional Topics"). Sections render in array order, and entries within a section
+ * render in array order.
+ *
+ * @category Doc Chrome
+ */
+export interface NavSection {
+    readonly entries: readonly DocEntry[];
+    readonly title: string;
+}
+/**
+ * One "other projects" entry for the webUI's project list. The rendered link text is `{title}: {blurb}`.
+ *
+ * @category Doc Chrome
+ */
+export interface ProjectEntry {
+    readonly blurb: string;
+    readonly href: string;
+    readonly title: string;
+}
+/**
+ * A manifest fragment whose data may be supplied inline (an array), read from a local file relative to the plugin root (`{ file }`), or fetched from a URL at stamp time
+ * (`{ url }`). The CLI resolves these; the renderers only ever see the resolved inline array. The URL form is what lets a family-wide list (the project list) live in one
+ * external file that every plugin's next build pulls from, without baking that list into this generic library.
+ *
+ * @category Doc Chrome
+ */
+export type ExternalSource<T> = readonly T[] | {
+    readonly file: string;
+} | {
+    readonly url: string;
+};
+/**
+ * The per-plugin documentation-chrome manifest - the single source of truth for a plugin's masthead, documentation index, dashboard badges, and project list. Authored
+ * once per plugin (a typed TS module or a static JSON file) and consumed by the `prepare-chrome` CLI subcommand.
+ *
+ * @category Doc Chrome
+ */
+export interface DocChromeManifest {
+    readonly devBadges?: readonly Badge[];
+    readonly masthead: Masthead;
+    readonly nav: readonly NavSection[];
+    readonly projects?: ExternalSource<ProjectEntry>;
+    readonly repo: RepoCoordinates;
+    readonly surfaces?: {
+        readonly readme?: string;
+        readonly webui?: string;
+    };
+}
+/**
+ * The surface a documentation index is rendered for. `"readme"` and `"doc-footer"` both render markdown; `"webui"` renders HTML. The surface also selects href
+ * derivation: `"readme"` uses in-README section anchors for `readme-anchor` entries, while `"doc-footer"` and `"webui"` use absolute blob URLs (an anchor entry viewed
+ * from anywhere other than the README itself must resolve to the README's absolute URL). Only `"doc-footer"` omits the current document from its own list.
+ *
+ * @category Doc Chrome
+ */
+export type NavSurface = "doc-footer" | "readme" | "webui";
+/**
+ * The opening marker of the auto-generated masthead region. See {@link renderMasthead}. The text doubles as an in-document warning not to edit the region by hand.
+ *
+ * @category Doc Chrome
+ */
+export declare const MASTHEAD_BEGIN = "<!-- MASTHEAD:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
+/**
+ * The closing marker of the auto-generated masthead region. See {@link MASTHEAD_BEGIN}.
+ *
+ * @category Doc Chrome
+ */
+export declare const MASTHEAD_END = "<!-- MASTHEAD:END -->";
+/**
+ * The opening marker of the auto-generated documentation-index region, used in the README's documentation section, each content doc's footer, and the webUI's Support
+ * tab. See {@link renderDocIndex}.
+ *
+ * @category Doc Chrome
+ */
+export declare const DOCUMENTATION_BEGIN = "<!-- DOCUMENTATION:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
+/**
+ * The closing marker of the auto-generated documentation-index region. See {@link DOCUMENTATION_BEGIN}.
+ *
+ * @category Doc Chrome
+ */
+export declare const DOCUMENTATION_END = "<!-- DOCUMENTATION:END -->";
+/**
+ * The opening marker of the auto-generated development-dashboard badge region (README only). See {@link renderDevBadges}.
+ *
+ * @category Doc Chrome
+ */
+export declare const DEV_BADGES_BEGIN = "<!-- DEV BADGES:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
+/**
+ * The closing marker of the auto-generated development-dashboard badge region. See {@link DEV_BADGES_BEGIN}.
+ *
+ * @category Doc Chrome
+ */
+export declare const DEV_BADGES_END = "<!-- DEV BADGES:END -->";
+/**
+ * The opening marker of the auto-generated project-list region (webUI only). See {@link renderProjects}.
+ *
+ * @category Doc Chrome
+ */
+export declare const PROJECTS_BEGIN = "<!-- PROJECTS:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
+/**
+ * The closing marker of the auto-generated project-list region. See {@link PROJECTS_BEGIN}.
+ *
+ * @category Doc Chrome
+ */
+export declare const PROJECTS_END = "<!-- PROJECTS:END -->";
+/**
+ * Render the masthead - the centered logo, the H1 title, the ordered badge row, and the H2 tagline - as the markdown/HTML block a plugin embeds at the top of its README
+ * and every content doc. The block is identical across those surfaces, so a single manifest drives all of them and the hand-copied mastheads collapse to one.
+ *
+ * @param manifest - The documentation-chrome manifest.
+ *
+ * @returns The rendered masthead block.
+ *
+ * @category Doc Chrome
+ */
+export declare function renderMasthead(manifest: DocChromeManifest): string;
+/**
+ * Render the development-dashboard badges - the README-only badge row (license, build status, dependencies, and the like) that sits apart from the masthead. Returns an
+ * empty string when the manifest declares no dashboard badges.
+ *
+ * @param manifest - The documentation-chrome manifest.
+ *
+ * @returns The rendered badge rows, one badge per line.
+ *
+ * @category Doc Chrome
+ */
+export declare function renderDevBadges(manifest: DocChromeManifest): string;
+/**
+ * Render the documentation index for a surface. On the markdown surfaces (`"readme"`, `"doc-footer"`) the output is one bullet per section with a nested bullet per
+ * entry; on `"webui"` it is one `<h5>` heading and `<ul>` per section. Href derivation follows the surface: in-README anchors on `"readme"`, absolute blob URLs
+ * elsewhere. A `"doc-footer"` render omits the current document (via `currentFile`) and drops any section left empty by that omission, so a doc's own footer never links
+ * back to itself.
+ *
+ * @param input
+ * @param input.currentFile - The doc file being rendered into, relative to the plugin root. Only consulted for the `"doc-footer"` surface, to omit the self-link.
+ * @param input.manifest    - The documentation-chrome manifest.
+ * @param input.surface     - The surface to render for.
+ *
+ * @returns The rendered documentation index.
+ *
+ * @category Doc Chrome
+ */
+export declare function renderDocIndex({ currentFile, manifest, surface }: {
+    currentFile?: string;
+    manifest: DocChromeManifest;
+    surface: NavSurface;
+}): string;
+/**
+ * Render the webUI project list - the "other projects" links - as an HTML `<ul>`. The CLI resolves the manifest's project source (inline, local file, or remote URL) to
+ * this array before calling; the renderer never performs I/O. Entries are rendered in alphabetical order by title, so the list reads predictably no matter what order the
+ * source - often a shared, remotely-fetched file every plugin points at - happens to hold. Each entry's link text is `{title}: {blurb}`.
+ *
+ * @param projects - The resolved project entries. Their order is not significant; the renderer sorts them by title.
+ *
+ * @returns The rendered project list.
+ *
+ * @category Doc Chrome
+ */
+export declare function renderProjects(projects: readonly ProjectEntry[]): string;
+/**
+ * Validate a loaded value and return it typed as a well-formed {@link DocChromeManifest}, failing fast with a framed diagnostic that names the manifest source and the
+ * offending field rather than surfacing an opaque error deep inside a renderer or a bare `resolve()` type error in the CLI. Validates every field the renderer or the
+ * CLI consumes - `masthead`, `nav`, `repo`, and the optional `devBadges` and `surfaces`. The project source is validated separately at resolution time, since it may be
+ * a remote reference rather than inline data.
+ *
+ * @param value  - The loaded manifest value, untrusted until validated.
+ * @param source - The manifest's path or module specifier, for diagnostics.
+ *
+ * @returns The same value, now typed as a validated {@link DocChromeManifest}.
+ *
+ * @category Doc Chrome
+ */
+export declare function parseDocChromeManifest(value: unknown, source: string): DocChromeManifest;
+/**
+ * Validate a resolved project source and return it typed as an array of {@link ProjectEntry}. The CLI calls this after resolving the manifest's project source - which
+ * may be inline data, a local file, or a remote URL - so a malformed external list fails fast with a framed diagnostic naming the source rather than rendering broken
+ * markup.
+ *
+ * @param value  - The resolved project value, untrusted until validated.
+ * @param source - The project source (a path or URL) for diagnostics.
+ *
+ * @returns The same value, now typed as a validated array of {@link ProjectEntry}.
+ *
+ * @category Doc Chrome
+ */
+export declare function parseProjectEntries(value: unknown, source: string): readonly ProjectEntry[];
+//# sourceMappingURL=docChrome.d.ts.map