homebridge-plugin-utils 2.0.0 → 2.2.0

package/build/tsconfig.json

@@ -31,6 +31,21 @@
     "noPropertyAccessFromIndexSignature": true,
     "noUncheckedIndexedAccess": true,
     "noUncheckedSideEffectImports": true,
+
+    /* Host-package type identity for composed development rigs. TypeScript unifies two physical copies of a package into one type identity only when their
+     * package name and version match exactly, so a plugin tree and a symlinked library tree holding different homebridge or hap-nodejs versions split every HAP
+     * type into two incompatible identities. Mapping the host packages to the extending project's own node_modules makes the consumer's copy the single source of
+     * type truth for the whole compilation - the same composition npm produces in a published install - so version skew surfaces only as genuine API
+     * incompatibilities. ${configDir} resolves to the directory of the final extending tsconfig, so every consumer resolves its own tree rather than this base
+     * file's. The mappings name each package's declaration entry file rather than its package directory: a paths substitution is a bare file lookup that never
+     * consults the target's package.json, so a directory target fails silently and resolution falls back to the importing file's own tree.
+     */
+    "paths": {
+
+      "@homebridge/hap-nodejs": ["${configDir}/node_modules/@homebridge/hap-nodejs/dist/index.d.ts"],
+      "homebridge": ["${configDir}/node_modules/homebridge/dist/index.d.ts"]
+    },
+
     "resolveJsonModule": true,
     "rewriteRelativeImportExtensions": true,
     "skipLibCheck": true,

package/dist/backpressure.d.ts

@@ -4,7 +4,7 @@ import type { Writable } from "node:stream";
  * 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 discriminate backpressure-overflow (back off and retry later)
+ * 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

package/dist/backpressure.js

@@ -17,7 +17,7 @@ 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 discriminate backpressure-overflow (back off and retry later)
+ * 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
@@ -109,7 +109,7 @@ export class BackpressureWriter {
         // 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
-        // idempotent after first settlement, so the second call is a no-op. Rejecting from here unconditionally is load-bearing in the stream-error escalation path,
+        // 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());
@@ -131,7 +131,7 @@ export class BackpressureWriter {
      */
     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 discriminate on `signal.reason` / `isHbpuAbortReason` in either case.
+        // mid-write abort path - callers branch on `signal.reason` / `isHbpuAbortReason` in either case.
         if (this.signal.aborted) {
             throw this.signal.reason;
         }
@@ -256,7 +256,7 @@ export class BackpressureWriter {
         }
     }
     // 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 idempotent after first settlement, so if the drain loop's catch branch also rejects the in-flight resolver
+    // 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.

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":"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"}

package/dist/cli/index.d.ts

@@ -1,4 +1,23 @@
 #!/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 { parseWebUiLoaderConfig, renderWebUiBootRegion } from "../webui-loader.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
@@ -12,27 +31,43 @@ export declare const USAGE: string;
  * 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
+ * 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 idempotently. A re-run against unchanged source content produces the same subdir name + same contents + same manifest. Stale prior-build subdirs are
+ * 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.
  *
+ * When the `loader` and `splice` namespaces are injected, a final step stamps the plugin's webUI script loader: the `index.html` beside the destination is read, its
+ * `WEBUI LOADER CONFIG` comment parsed, the loader block rendered from that config plus this run's `libPath` and package name, and spliced into its marked region with
+ * an atomic `.tmp` + rename. The step is marker-gated - no `index.html`, or no BEGIN marker, is a silent no-op - so a plugin that has not opted in, and every
+ * no-injection caller, mirror exactly as before. The stamp derives from the same package name and destination the mirror used, so the two never drift.
+ *
  * @param args
  * @param args.dest       - The plugin's destination directory (typically `homebridge-ui/public/lib`). Created if missing.
+ * @param args.loader     - The injected webUI-loader namespace (marker constants, `parseWebUiLoaderConfig`, `renderWebUiBootRegion`). Absent = no stamp step, so the
+ *                          mirror-only path and its existing tests are untouched. Supplied with `splice`, it stamps the plugin's `index.html` loader region.
  * @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.
+ * @param args.splice     - The injected {@link spliceMarkedRegion} that replaces the loader's marked region. Paired with `loader`; absent = no stamp step.
  *
- * @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.
+ * @throws When the source has not been built (`dist/ui/` missing), the source `package.json` lacks a `version` field (or, when stamping, a `name` field), or the source
+ *         `dist/ui` path exists but is not a directory; and, when stamping, propagates the parse/splice framed errors under a "mirror succeeded, stamp failed" frame.
  */
-export declare function prepareUi({ dest, sourceRoot }: {
+export declare function prepareUi({ dest, loader, sourceRoot, splice }: {
     dest: string;
+    loader?: WebUiLoaderModule;
     sourceRoot: string;
+    splice?: typeof spliceMarkedRegion;
 }): Promise<void>;
+interface WebUiLoaderModule {
+    readonly WEBUI_LOADER_BEGIN: string;
+    readonly WEBUI_LOADER_END: string;
+    readonly parseWebUiLoaderConfig: typeof parseWebUiLoaderConfig;
+    readonly renderWebUiBootRegion: typeof renderWebUiBootRegion;
+}
 /**
  * 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
@@ -71,6 +106,58 @@ export declare function prepareDocs({ catalogModulePath, docPath, render, splice
     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
@@ -92,4 +179,5 @@ export declare function runCli({ argv, cwd, sourceRoot, stderr }: {
         write: (chunk: string) => unknown;
     };
 }): Promise<number>;
+export {};
 //# sourceMappingURL=index.d.ts.map