homebridge-plugin-utils 1.35.0 → 2.0.0

package/dist/cli/index.js

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * cli/index.ts: The homebridge-plugin-utils command-line interface.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * 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`
+ * and `prepareDocs` 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` / `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 { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createHash } from "node:crypto";
+import { parseArgs } from "node:util";
+import { realpathSync } from "node:fs";
+// Semver-shaped subdir names that {@link prepareUi} owns. Only entries matching this pattern are candidates for the stale-build sweep; anything else in the
+// destination is left alone. Pattern matches `MAJOR.MINOR.PATCH` plus the optional pre-release (`-...`) and build-metadata (`+...`) segments semver permits, so a
+// plugin author who happens to name a subdir `assets` or `i18n` is never at risk of having it removed. The hash-suffixed shape this CLI writes (e.g.,
+// `2.0.0-abc1234567890def`) falls into the pre-release segment, so the same pattern catches stale released-version directories from prior tooling and stale
+// hash-suffixed directories from prior runs alike.
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/;
+// Truncated SHA-256 length used for the content-hash segment of the subdir name. 16 hex chars (64 bits) put the birthday-paradox collision threshold near ~2^32
+// distinct builds (a chance collision between any specific pair is 2^-64), more than sufficient for cache-busting. Matches the truncation convention modern bundlers
+// (Vite, Next.js, esbuild, webpack) use for the same purpose: short enough to scan visually in a path, long enough that a chance collision between two builds is
+// astronomically unlikely.
+const HASH_LENGTH = 16;
+/**
+ * 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 const USAGE = "Usage: homebridge-plugin-utils <command> [options]\n\n" +
+    "Commands:\n  prepare-ui <destination>    Mirror HBPU's webUI into the plugin's lib directory.\n" +
+    "  prepare-docs <catalog-module> [--doc <path>]    Generate the Feature Options reference into the plugin's docs.\n";
+/**
+ * Compute a deterministic content hash over `root`'s file tree. Walks every file in lexicographic order of relative POSIX path so two runs against the same content
+ * produce the same hash regardless of underlying filesystem ordering or the absolute path the tree sits at. Mixes both the relative path and the file bytes into
+ * the hash so renames produce a different output even when content bytes are unchanged - that is the correct cache-bust semantic, since a rename is a visible
+ * difference to any consumer importing the file by name.
+ *
+ * The null-byte (`\0`) delimiters between path and content prevent the synthetic boundary-blurring case where a long path concatenated with a short content could
+ * share its hash input with a shorter path concatenated with a longer content. SHA-256's preimage resistance covers anything more contrived, but the explicit
+ * delimiter is the discipline that makes the hash input unambiguous on its face.
+ *
+ * Returns the first {@link HASH_LENGTH} hex characters of the hash. Truncation is deliberate: full SHA-256 (64 hex chars) would bloat the URL path and the
+ * filesystem display without earning meaningful collision resistance for this use case.
+ *
+ * @param root - The directory whose tree contents are hashed.
+ *
+ * @returns The truncated hex hash, suitable for use as a path segment.
+ */
+async function computeContentHash(root) {
+    // Node 22's recursive readdir plus `withFileTypes: true` gives us a flat Dirent[] for the entire tree in one syscall, eliminating the manual stack-walk that
+    // older Node versions required. `parentPath` is the non-deprecated way to recover each entry's directory (the `path` alias was deprecated in Node 20.12 /
+    // 21.4); using it here keeps the implementation aligned with current Node idioms.
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    const filePaths = entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => join(entry.parentPath, entry.name))
+        .toSorted();
+    // Read every file's bytes in parallel, then feed them into the hasher sequentially. Parallel reads keep the I/O latency bound to the slowest single file rather
+    // than the sum of all files; the sequential hash update is required because the hasher is stateful and must consume bytes in the canonical sorted order to
+    // produce the same digest every run.
+    const fileBytes = await Promise.all(filePaths.map(async (path) => ({ bytes: await readFile(path), path })));
+    const hasher = createHash("sha256");
+    for (const { bytes, path } of fileBytes) {
+        // Normalize separators to POSIX form so a hash computed on a Windows build matches a hash computed on Linux for the same tree contents. The relative path
+        // anchors the hash to the tree structure (not the absolute location), so the same source tree built into `/tmp/a/dist/ui` and `/var/build/b/dist/ui` produces
+        // an identical hash.
+        const rel = relative(root, path).split(sep).join("/");
+        hasher.update(rel);
+        hasher.update("\0");
+        hasher.update(bytes);
+        hasher.update("\0");
+    }
+    return hasher.digest("hex").slice(0, HASH_LENGTH);
+}
+/**
+ * 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 the load-bearing piece for the maintainer-iteration use case. 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 idempotently. 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 async function prepareUi({ dest, sourceRoot }) {
+    const sourceUiDir = join(sourceRoot, "dist", "ui");
+    const sourcePackageJson = join(sourceRoot, "package.json");
+    // Validate the source side first so failures name the corrective action rather than the operation we couldn't perform. The two ways the source can be wrong are
+    // structurally distinct: `dist/ui` missing means HBPU hasn't been built; `package.json` missing or version-less means the package is malformed. Both surface as
+    // typed errors with the path that diagnosed the problem.
+    let sourceUiStat;
+    try {
+        sourceUiStat = await stat(sourceUiDir);
+    }
+    catch {
+        throw new Error("HBPU has not been built: " + sourceUiDir + " is missing. Run `npm run build` in HBPU first.");
+    }
+    if (!sourceUiStat.isDirectory()) {
+        throw new Error("HBPU source path is not a directory: " + sourceUiDir + ".");
+    }
+    const packageManifestRaw = await readFile(sourcePackageJson, "utf8");
+    const packageManifest = JSON.parse(packageManifestRaw);
+    const version = packageManifest.version;
+    if (!version) {
+        throw new Error("HBPU package.json at " + sourcePackageJson + " has no version field.");
+    }
+    // Compute the content hash before any destination work begins so the source side is fully validated and characterized before we touch the plugin's directory.
+    // The subdir name combines version + hash: version stays the human-readable, operator-recognizable segment; hash supplies the change-detection that makes the
+    // cache invalidation structurally complete across both maintainer-iteration and published-release use cases.
+    const hash = await computeContentHash(sourceUiDir);
+    const subdir = version + "-" + hash;
+    // Resolve the destination to an absolute path up front so every subsequent path operation reads against the same canonical base. The destination is created via
+    // `mkdir({ recursive: true })` rather than relying on `cp` to lazily create it, so the readdir-based stale-build sweep below can run against a known-extant
+    // directory on every invocation (including the first run against a never-before-existing path).
+    const absDest = resolve(dest);
+    await mkdir(absDest, { recursive: true });
+    const versionedDest = join(absDest, subdir);
+    // Idempotent reset of the versioned subdir. Wipe first so the copy step always starts from a known-empty target; the same-content idempotency property is upheld
+    // by the hash being a deterministic function of the source, so re-running with unchanged content produces the same subdir name + same contents + same manifest,
+    // even though the implementation re-does the work. `force: true` swallows ENOENT so a first run against an empty destination doesn't surface the missing-target
+    // as an error.
+    await rm(versionedDest, { force: true, recursive: true });
+    await cp(sourceUiDir, versionedDest, { recursive: true });
+    // Destination manifest sits at the top of `dest`, NOT inside the versioned subdir. The plugin's `index.html` reads it (with `cache: "no-store"`) to discover
+    // which subdir to load from. Every manifest field serves a distinct purpose: `version` for human-readable identification, `hash` for change-detection, `subdir`
+    // for the canonical "where to load from" answer that consumers reference directly without reconstructing the join. The join convention stays here in the
+    // producer; if we ever change it (different delimiter, different segment order), no consumer breaks. Pretty-printed JSON because the file is human-read often
+    // enough to matter (debugging sessions, README screenshots, support requests).
+    await writeFile(join(absDest, "manifest.json"), JSON.stringify({ hash, subdir, version }, null, 2) + "\n");
+    // Sweep stale versioned subdirs from prior runs. The semver-shape filter is the discipline that keeps the sweep narrow: anything in the destination that doesn't
+    // look like a version we own (plugin's own files, sibling tools, hand-curated content) survives untouched. The current subdir is skipped here since we just
+    // (re)created it above; the loop targets only OLDER builds left over from prior runs (different version, different hash, or both).
+    const entries = await readdir(absDest, { withFileTypes: true });
+    await Promise.all(entries
+        .filter((entry) => entry.isDirectory() && VERSION_PATTERN.test(entry.name) && (entry.name !== subdir))
+        .map((entry) => rm(join(absDest, entry.name), { force: true, recursive: true })));
+}
+/**
+ * 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 async function prepareDocs({ catalogModulePath, docPath, render, splice }) {
+    // Load the catalog by dynamic import. A bare absolute filesystem path is not a portable ESM specifier (Windows drive letters in particular are mis-parsed), so we
+    // convert it to a `file:` URL first - the same indirection the `hblog` bin uses to reach its sibling library from a single-file launcher. The namespace is typed with
+    // the required catalog exports plus the OPTIONAL scope hooks, each `unknown` until validated below - the same honest-until-checked shape the catalog arrays
+    // carry, so nothing reaches the renderer as a mis-typed value.
+    const catalog = await import(__rewriteRelativeImportExtension(pathToFileURL(catalogModulePath).href));
+    // Validate the catalog's required exports before rendering so a mis-built or wrong-module path fails with a diagnostic that names what is wrong and where,
+    // rather than surfacing as an opaque type error deep inside the renderer's traversal.
+    if (!Array.isArray(catalog.featureOptionCategories)) {
+        throw new Error("Catalog module " + catalogModulePath + " does not export a `featureOptionCategories` array.");
+    }
+    if ((typeof catalog.featureOptions !== "object") || (catalog.featureOptions === null)) {
+        throw new Error("Catalog module " + catalogModulePath + " does not export a `featureOptions` object.");
+    }
+    // Validate every OPTIONAL scope hook independently. Each is present-but-must-be-a-function or absent: a present non-function is a mis-shaped catalog and fails
+    // with a diagnostic naming the module and the offending export (the same framing the required exports use), while an absent hook stays `undefined` and is inert -
+    // the renderer treats a missing hook as "omit cleanly", so the zero-hook path (ratgdo) is unchanged. We check before casting so the cast to the renderer's hook
+    // parameter type only happens once the value is known to be callable, mirroring how the catalog arrays are cast only after their shape guard.
+    if ((catalog.describeCategoryScope !== undefined) && (typeof catalog.describeCategoryScope !== "function")) {
+        throw new Error("Catalog module " + catalogModulePath + " exports a non-function `describeCategoryScope`.");
+    }
+    if ((catalog.describeOptionScope !== undefined) && (typeof catalog.describeOptionScope !== "function")) {
+        throw new Error("Catalog module " + catalogModulePath + " exports a non-function `describeOptionScope`.");
+    }
+    // Render the live catalog into the markdown fragment. The optional scope hooks are forwarded through alongside the catalog; an `undefined` hook is inert, so a
+    // zero-hook catalog renders cleanly. The renderer is the single source of truth for the index, the per-category tables, and the scope prose the optional hooks
+    // contribute, while this function only wires the catalog and its hooks to it. Each hook is cast to the renderer's parameter type only after its function
+    // guard above, the same discipline the catalog arrays follow.
+    const reference = render({ categories: catalog.featureOptionCategories,
+        describeCategoryScope: catalog.describeCategoryScope,
+        describeOptionScope: catalog.describeOptionScope,
+        options: catalog.featureOptions });
+    // Read the existing doc and splice the rendered fragment in place between the markers, leaving the hand-written header and intro untouched. The splice throws its
+    // own framed errors on a missing or ambiguous marker pair; we let those propagate so the dispatch site frames them uniformly.
+    const source = await readFile(docPath, "utf8");
+    const updated = splice(source, reference);
+    // Atomic write: stage in a sibling temp file, then rename over the doc.
+    await writeFile(docPath + ".tmp", updated, "utf8");
+    await rename(docPath + ".tmp", docPath);
+}
+/**
+ * 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 async function runCli({ argv, cwd, sourceRoot, stderr }) {
+    // parseArgs runs in strict mode, so an unrecognized flag (e.g. a typo'd `--docs`) throws `ERR_PARSE_ARGS_UNKNOWN_OPTION` here rather than falling through to the
+    // usage banner. That throw is intentionally uncaught - the per-case try/catch blocks below wrap only the subcommand work - so it surfaces as a rejected `runCli`
+    // promise at the entry point, distinct from the default case's banner handling for an unknown positional command.
+    const { positionals, values } = parseArgs({ allowPositionals: true, args: [...argv], options: { doc: { type: "string" } }, strict: true });
+    const [command, ...rest] = positionals;
+    switch (command) {
+        case "prepare-ui": {
+            const [destination] = rest;
+            if (!destination) {
+                stderr.write("homebridge-plugin-utils prepare-ui: missing required destination argument.\n");
+                return 1;
+            }
+            try {
+                await prepareUi({ dest: destination, sourceRoot });
+            }
+            catch (error) {
+                stderr.write("homebridge-plugin-utils prepare-ui: " + (error instanceof Error ? error.message : String(error)) + "\n");
+                return 1;
+            }
+            return 0;
+        }
+        case "prepare-docs": {
+            const [catalogArg] = rest;
+            if (!catalogArg) {
+                stderr.write("homebridge-plugin-utils prepare-docs: missing required catalog-module argument.\n");
+                return 1;
+            }
+            // Resolve both paths against the injected working directory. The catalog argument is the plugin's compiled options module; the doc defaults to the family's
+            // canonical `docs/FeatureOptions.md` and is overridable through `--doc` for a plugin that ships its reference elsewhere.
+            const catalogModulePath = resolve(cwd, catalogArg);
+            const docPath = resolve(cwd, values.doc ?? "docs/FeatureOptions.md");
+            // Reach HBPU's own renderer through a computed dynamic import of its compiled module - never a static relative import - so the single-file bin stays
+            // symlink-safe (it imports only `node:` builtins at load time). A failed import here means HBPU itself has not been built, which is a distinct, actionable
+            // condition from a downstream render/splice failure, so we frame it separately and point at the corrective action.
+            const rendererPath = join(sourceRoot, "dist", "featureOptions-docs.js");
+            let renderer;
+            try {
+                renderer = await import(__rewriteRelativeImportExtension(pathToFileURL(rendererPath).href));
+            }
+            catch {
+                stderr.write("homebridge-plugin-utils prepare-docs: HBPU has not been built: " + rendererPath + " is missing. Run `npm run build` in HBPU first.\n");
+                return 1;
+            }
+            try {
+                await prepareDocs({ catalogModulePath, docPath, render: renderer.renderFeatureOptionsReference, splice: renderer.spliceMarkedRegion });
+            }
+            catch (error) {
+                stderr.write("homebridge-plugin-utils prepare-docs: " + (error instanceof Error ? error.message : String(error)) + "\n");
+                return 1;
+            }
+            return 0;
+        }
+        default: {
+            stderr.write(USAGE);
+            // A bare `homebridge-plugin-utils` invocation (no command at all) is treated as a help request and exits 0; an unknown command is a misuse and exits 1. Both
+            // write the usage banner so the user sees the same prompt either way - only the exit code differentiates.
+            return command ? 1 : 0;
+        }
+    }
+}
+/**
+ * Decide whether this module is the program entry point (run as the bin) versus imported as a library (by the test suite). Canonicalizes the real path of both the
+ * launch path (`process.argv[1]`) and this module's own URL before comparing them.
+ *
+ * The realpath normalization is the load-bearing detail. npm exposes a bin as a symlink in `node_modules/.bin`, so under default Node the launch path is the
+ * symlink while `import.meta.url` is the resolved target - a raw string comparison never matches and the CLI silently does nothing. Canonicalizing both sides
+ * collapses that indirection (and any `file:`-dependency, copied-package, or `--preserve-symlinks` layout) to a single real path, so the check holds however the
+ * launcher reached this file. We keep this explicit realpath comparison rather than deferring to `import.meta.main`: the symlink and copied-package indirection is the
+ * load-bearing concern the entry-point check exists to handle, and resolving it explicitly keeps that handling visible at the call site.
+ *
+ * @returns `true` when invoked as the program entry, `false` when imported or when the launch path cannot be resolved.
+ */
+function isEntryPoint() {
+    const entryPath = process.argv[1];
+    if (!entryPath) {
+        return false;
+    }
+    try {
+        return realpathSync(entryPath) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        // A realpath throws only when a path does not resolve on disk - not a state a genuine entry-point invocation reaches, so treat it as "not the entry."
+        return false;
+    }
+}
+// Execute the CLI when this module is the program entry point. When imported by the test suite instead, `isEntryPoint()` is false and the module exposes
+// `prepareUi` / `prepareDocs` / `runCli` / `USAGE` as a side-effect-free library surface.
+if (isEntryPoint()) {
+    // Resolve HBPU's package root from this file's real location. The compiled CLI sits at `dist/cli/index.js`; walking two segments up from its real directory
+    // reaches the package root regardless of how the package is installed (a plugin's `node_modules`, a workspace symlink, a global install) or which Node
+    // symlink-resolution mode is in effect - the realpath has already collapsed any indirection.
+    const sourceRoot = resolve(dirname(realpathSync(fileURLToPath(import.meta.url))), "..", "..");
+    process.exit(await runCli({ argv: process.argv.slice(2), cwd: process.cwd(), sourceRoot, stderr: process.stderr }));
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

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

package/dist/clock-double.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A reusable, controllable {@link Clock} test double.
+ *
+ * The {@link Clock} seam in `clock.ts` exists so a consuming plugin's time-dependent code can be driven without real wall-clock waits. This module ships the fake that
+ * cashes that in: a {@link TestClock} over a virtual timeline a test advances explicitly. `now()` returns the virtual time; `delay()` registers a pending wait that
+ * resolves only when {@link TestClock.advance} crosses its deadline, or rejects when its signal aborts - matching `node:timers/promises` `setTimeout`'s `AbortError`
+ * shape. No real timers and no wall-clock are used, so a consumer's pacing/timeout/duration path runs deterministically and instantly under test.
+ *
+ * The double builds on the library's own primitives rather than hand-rolling them: {@link onAbort} wires the abort listener and yields the `Disposable` that detaches
+ * it, and `Promise.withResolvers` captures each pending wait's deferred. The abort listener is detached on EITHER resolution path (deadline-crossed or aborted), so no
+ * listener leaks onto a long-lived signal across many short waits.
+ *
+ * @module
+ */
+import type { Clock } from "./clock.ts";
+/**
+ * A controllable {@link Clock} double over virtual time. `now()` returns the current virtual time; `delay()` registers a pending wait that resolves only when
+ * {@link TestClock.advance} crosses its deadline (in ascending-deadline order), or rejects with an `AbortError` (matching `node:timers/promises` `setTimeout` - `name`
+ * `"AbortError"`, `code` `"ABORT_ERR"`, NOT the signal's reason) when its signal aborts. No real timers or wall-clock are used.
+ *
+ * The virtual time is a RELATIVE timeline seeded at `start` (default `0`), NOT real epoch milliseconds. A consumer that compares `now()` against an absolute real-epoch
+ * constant would diverge; consumers must only compare `now()` values to each other (deriving elapsed intervals from differences), which is the only use a
+ * `Date.now()`-style read serves in the consuming pacing path - all its time reads come from the one injected clock.
+ *
+ * @example
+ *
+ * ```ts
+ * import { TestClock } from "homebridge-plugin-utils";
+ *
+ * const clock = new TestClock();
+ *
+ * const waited = clock.delay(100);
+ *
+ * // Nothing resolves until virtual time crosses the deadline.
+ * clock.advance(100);
+ *
+ * await waited;
+ * ```
+ *
+ * @see Clock
+ *
+ * @category Testing
+ */
+export declare class TestClock implements Clock {
+    #private;
+    /**
+     * Construct a clock seeded at `start` (default `0`). The seed is the initial value `now()` returns; `advance` moves it forward (or back, for a negative delta).
+     *
+     * @param start - The initial virtual time, in the consumer's relative timeline. Defaults to `0`.
+     */
+    constructor(start?: number);
+    /**
+     * Advance virtual time by `ms` and resolve every delay whose deadline the new time has reached. The delta is applied regardless of sign, so a negative `ms` moves time
+     * backward; `advance(0)` moves time nowhere but STILL flushes any already-due entry (a `delay(0)` or a `delay` with a non-positive `ms`), so a zero or negative delay
+     * is never a lost wakeup.
+     *
+     * Due entries resolve in ASCENDING deadline order; entries that share a deadline keep their FIFO registration order, because the snapshot is taken before any removal
+     * and the numeric sort is stable - matching how `setTimeout` fires equal-deadline timers in scheduling order. Each due entry is removed by identity and has its abort
+     * listener detached before it resolves, so the resolve path leaks no listener and the iteration is immune to the index shifts a forward in-place splice would cause.
+     *
+     * @param ms - The amount of virtual time to advance, in milliseconds. May be zero or negative.
+     */
+    advance(ms: number): void;
+    /**
+     * Register a delay that resolves when virtual time reaches `this.now() + ms`, or rejects with an `AbortError` (matching `node:timers/promises`) if `init.signal` aborts
+     * first. A non-positive `ms` yields a deadline at or before the current time, which the very next {@link TestClock.advance} (including `advance(0)`) flushes.
+     *
+     * A pre-aborted signal rejects on the executor's microtask exactly as `systemClock` does (NOT a synchronous throw): {@link onAbort} fires the handler inline, which
+     * removes the just-registered entry and rejects, so the entry never lingers in `pending`.
+     *
+     * @param ms   - The delay, in milliseconds. May be zero or negative (flushed by the next `advance`).
+     * @param init - Optional init options. A supplied `signal` rejects the wait with an `AbortError` when it aborts.
+     *
+     * @returns A promise that resolves when the deadline is crossed, or rejects with an `AbortError` if the signal aborts first.
+     */
+    delay(ms: number, init?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Return the current virtual time. Compare these values to each other to derive elapsed intervals - they are a relative timeline, not real epoch milliseconds.
+     *
+     * @returns The current virtual time.
+     */
+    now(): number;
+    /**
+     * The number of registered delays that have neither resolved nor rejected. A test reads this to assert a consumer registered its waits and later cleared them (no
+     * leak).
+     *
+     * @returns The count of unsettled delays.
+     */
+    get pending(): number;
+}
+//# sourceMappingURL=clock-double.d.ts.map

package/dist/clock-double.js

@@ -0,0 +1,141 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * clock-double.ts: A reusable, controllable Clock test double - virtual time a test advances explicitly - for the injectable Clock seam in clock.ts.
+ */
+import { onAbort } from "./util.js";
+/**
+ * Construct the rejection a {@link TestClock} `delay` produces when its signal aborts, matching `node:timers/promises` `setTimeout` exactly: a plain `Error` whose `name`
+ * is `"AbortError"` and whose `code` is the STRING `"ABORT_ERR"`. The real primitive's rejection is a dedicated internal class (not a `DOMException`, whose `code` is the
+ * numeric `20`, and there is no constructable `AbortError` global), so the double cannot match the constructor or prototype identity - it matches the observable `name`
+ * and `code` a consumer discriminates on, which is the contract that matters.
+ *
+ * @returns The `AbortError`-shaped rejection.
+ */
+function abortError() {
+    const error = new Error("The operation was aborted");
+    error.name = "AbortError";
+    // `code` is not a standard `Error` field, so assign it through an indexed widening rather than declaring a one-off subclass. The STRING value is what the real
+    // `node:timers/promises` rejection carries and what a consumer's `error.code === "ABORT_ERR"` check reads.
+    error.code = "ABORT_ERR";
+    return error;
+}
+/**
+ * A controllable {@link Clock} double over virtual time. `now()` returns the current virtual time; `delay()` registers a pending wait that resolves only when
+ * {@link TestClock.advance} crosses its deadline (in ascending-deadline order), or rejects with an `AbortError` (matching `node:timers/promises` `setTimeout` - `name`
+ * `"AbortError"`, `code` `"ABORT_ERR"`, NOT the signal's reason) when its signal aborts. No real timers or wall-clock are used.
+ *
+ * The virtual time is a RELATIVE timeline seeded at `start` (default `0`), NOT real epoch milliseconds. A consumer that compares `now()` against an absolute real-epoch
+ * constant would diverge; consumers must only compare `now()` values to each other (deriving elapsed intervals from differences), which is the only use a
+ * `Date.now()`-style read serves in the consuming pacing path - all its time reads come from the one injected clock.
+ *
+ * @example
+ *
+ * ```ts
+ * import { TestClock } from "homebridge-plugin-utils";
+ *
+ * const clock = new TestClock();
+ *
+ * const waited = clock.delay(100);
+ *
+ * // Nothing resolves until virtual time crosses the deadline.
+ * clock.advance(100);
+ *
+ * await waited;
+ * ```
+ *
+ * @see Clock
+ *
+ * @category Testing
+ */
+export class TestClock {
+    // The current virtual time. Seeded by the constructor and moved only by `advance`.
+    #now;
+    // The registered, not-yet-settled delays. An entry leaves this list exactly once - either when `advance` crosses its deadline or when its signal aborts - via
+    // `#remove`, which splices by identity so a mixed resolve-and-abort sequence never strands or mis-removes an entry.
+    #pending = [];
+    /**
+     * Construct a clock seeded at `start` (default `0`). The seed is the initial value `now()` returns; `advance` moves it forward (or back, for a negative delta).
+     *
+     * @param start - The initial virtual time, in the consumer's relative timeline. Defaults to `0`.
+     */
+    constructor(start = 0) {
+        this.#now = start;
+    }
+    /**
+     * Advance virtual time by `ms` and resolve every delay whose deadline the new time has reached. The delta is applied regardless of sign, so a negative `ms` moves time
+     * backward; `advance(0)` moves time nowhere but STILL flushes any already-due entry (a `delay(0)` or a `delay` with a non-positive `ms`), so a zero or negative delay
+     * is never a lost wakeup.
+     *
+     * Due entries resolve in ASCENDING deadline order; entries that share a deadline keep their FIFO registration order, because the snapshot is taken before any removal
+     * and the numeric sort is stable - matching how `setTimeout` fires equal-deadline timers in scheduling order. Each due entry is removed by identity and has its abort
+     * listener detached before it resolves, so the resolve path leaks no listener and the iteration is immune to the index shifts a forward in-place splice would cause.
+     *
+     * @param ms - The amount of virtual time to advance, in milliseconds. May be zero or negative.
+     */
+    advance(ms) {
+        this.#now += ms;
+        // Snapshot the due entries BEFORE mutating `#pending`, then sort them into deadline order. Filtering off a live array while removing from it would shift indices and
+        // strand entries; the snapshot first decouples the iteration from the removal. The sort is a stable numeric comparator, so equal deadlines preserve FIFO order.
+        const due = this.#pending.filter((entry) => entry.deadline <= this.#now).sort((a, b) => a.deadline - b.deadline);
+        for (const entry of due) {
+            // Remove by identity first so a re-entrant observer sees the correct `pending` count, then detach the abort listener (present only when this delay had a signal) so
+            // the resolve path leaves no listener on a long-lived signal, then settle the caller's promise.
+            this.#remove(entry);
+            entry.dispose?.[Symbol.dispose]();
+            entry.resolve();
+        }
+    }
+    /**
+     * Register a delay that resolves when virtual time reaches `this.now() + ms`, or rejects with an `AbortError` (matching `node:timers/promises`) if `init.signal` aborts
+     * first. A non-positive `ms` yields a deadline at or before the current time, which the very next {@link TestClock.advance} (including `advance(0)`) flushes.
+     *
+     * A pre-aborted signal rejects on the executor's microtask exactly as `systemClock` does (NOT a synchronous throw): {@link onAbort} fires the handler inline, which
+     * removes the just-registered entry and rejects, so the entry never lingers in `pending`.
+     *
+     * @param ms   - The delay, in milliseconds. May be zero or negative (flushed by the next `advance`).
+     * @param init - Optional init options. A supplied `signal` rejects the wait with an `AbortError` when it aborts.
+     *
+     * @returns A promise that resolves when the deadline is crossed, or rejects with an `AbortError` if the signal aborts first.
+     */
+    delay(ms, init) {
+        const { promise, reject, resolve } = Promise.withResolvers();
+        const entry = { deadline: this.#now + ms, resolve };
+        // Register the entry FIRST so a pre-aborted signal's inline `onAbort` handler (below) can find and remove it. `onAbort` runs the handler synchronously when the
+        // signal is already aborted, so for a pre-aborted signal the entry is pushed and then immediately removed-and-rejected within this call - settling on the executor's
+        // microtask, identical to `systemClock`. When no signal is supplied, `dispose` stays undefined and the entry only ever leaves via `advance`.
+        this.#pending.push(entry);
+        if (init?.signal !== undefined) {
+            entry.dispose = onAbort(init.signal, () => {
+                this.#remove(entry);
+                reject(abortError());
+            });
+        }
+        return promise;
+    }
+    /**
+     * Return the current virtual time. Compare these values to each other to derive elapsed intervals - they are a relative timeline, not real epoch milliseconds.
+     *
+     * @returns The current virtual time.
+     */
+    now() {
+        return this.#now;
+    }
+    /**
+     * The number of registered delays that have neither resolved nor rejected. A test reads this to assert a consumer registered its waits and later cleared them (no
+     * leak).
+     *
+     * @returns The count of unsettled delays.
+     */
+    get pending() {
+        return this.#pending.length;
+    }
+    // Remove `entry` from `#pending` by identity. Idempotent: a guarded `indexOf` + `splice` makes a second removal (e.g. an abort that races a resolve) a safe no-op and
+    // never removes the wrong entry, so `#pending` stays consistent across any resolve-and-abort interleaving.
+    #remove(entry) {
+        const index = this.#pending.indexOf(entry);
+        if (index !== -1) {
+            this.#pending.splice(index, 1);
+        }
+    }
+}
+//# sourceMappingURL=clock-double.js.map

package/dist/clock-double.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock-double.js","sourceRoot":"","sources":["../src/clock-double.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC;;;;;;;GAOG;AACH,SAAS,UAAU;IAEjB,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAErD,KAAK,CAAC,IAAI,GAAG,YAAY,CAAC;IAE1B,+JAA+J;IAC/J,2GAA2G;IAC1G,KAAkC,CAAC,IAAI,GAAG,WAAW,CAAC;IAEvD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,SAAS;IAEpB,mFAAmF;IACnF,IAAI,CAAS;IAEb,8JAA8J;IAC9J,oHAAoH;IAC3G,QAAQ,GAAiB,EAAE,CAAC;IAErC;;;;OAIG;IACH,YAAmB,KAAK,GAAG,CAAC;QAE1B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;IACpB,CAAC;IAED;;;;;;;;;;OAUG;IACI,OAAO,CAAC,EAAU;QAEvB,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAEhB,qKAAqK;QACrK,gKAAgK;QAChK,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QAEjH,KAAI,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;YAEvB,oKAAoK;YACpK,gGAAgG;YAChG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,EAAU,EAAE,IAA+B;QAEtD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAA+B,OAAO,CAAC,aAAa,EAAE,CAAC;QACzF,MAAM,KAAK,GAAe,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC;QAEhE,gKAAgK;QAChK,qKAAqK;QACrK,6IAA6I;QAC7I,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAE1B,IAAG,IAAI,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;YAE9B,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;gBAExC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;YACvB,CAAC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACI,GAAG;QAER,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;;;OAKG;IACH,IAAW,OAAO;QAEhB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,sKAAsK;IACtK,2GAA2G;IAC3G,OAAO,CAAC,KAAiB;QAEvB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAE3C,IAAG,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;YAEhB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;CACF"}