homebridge-plugin-utils 1.35.0 → 2.1.0

package/README.md

@@ -14,7 +14,7 @@ The design decisions are driven by my own needs as I continue to create, evolve,
 
 ### Features
 
-- **Feature options*.* Feature options are a hierarchical configuration system and matching webUI that allows users to set global defaults and override them at a granular level, enabling easier mass-customization of capabilities. For plugins that can potentially enumerate dozens of devices, this comes in quite handy so you don't need to configure each and every device, and instead you can focus on the exceptions.
+- **Feature options.** Feature options are a hierarchical configuration system and matching webUI that allows users to set global defaults and override them at a granular level, enabling easier mass-customization of capabilities. For plugins that can potentially enumerate dozens of devices, this comes in quite handy so you don't need to configure each and every device, and instead you can focus on the exceptions.
 
 - **Configuration webUI.** This a rich, custom webUI for enumerating all the devices a plugin knows about, and configuring feature options.
 
@@ -22,11 +22,139 @@ The design decisions are driven by my own needs as I continue to create, evolve,
 
 - **MQTT client.** Building in MQTT client capabilities is made easier through a set of utilities that allow you to easily publish and subscribe to events.
 
+- **`hblog` log client.** A zero-dependency tool for tailing and querying a `homebridge-config-ui-x` log, usable both as the `hblog` command-line bin and as the importable `HomebridgeLogClient` API. See [Log Client (`hblog`)](#log-client-hblog) below.
+
+- **Plugin tooling.** A `homebridge-plugin-utils` command-line tool that mirrors the compiled webUI into your plugin under a content-hashed folder (so the browser never serves a stale copy after a rebuild) and regenerates your Feature Options reference from its catalog (so the docs can't drift). See [Plugin Tooling (`prepare-ui` and `prepare-docs`)](#plugin-tooling-prepare-ui-and-prepare-docs) below.
+
 - **And more...**
 
 ## Documentation
 
-Documentation and examples for using this library to simplify and enhance Homebridge plugin development, especially camera-related plugins, is [available here](https://github.com/hjdhjd/homebridge-plugin-utils/blob/main/docs/README.md). Additionally, if you'd like to see this library being used n a well-documented, real-world example, please take a good look at my [homebridge-unifi-protect](https://github.com/hjdhjd/homebridge-unifi-protect) project. It relies heavily on this library for much of the functionality it provides.
+Documentation and examples for using this library to simplify and enhance Homebridge plugin development, especially camera-related plugins, is [available here](https://github.com/hjdhjd/homebridge-plugin-utils/blob/main/docs/README.md). Additionally, if you'd like to see this library being used in a well-documented, real-world example, please take a good look at my [homebridge-unifi-protect](https://github.com/hjdhjd/homebridge-unifi-protect) project. It relies heavily on this library for much of the functionality it provides.
+
+## Log Client (`hblog`)
+
+`hblog` is a zero-dependency tool for tailing and querying the log of a [homebridge-config-ui-x](https://github.com/homebridge/homebridge-config-ui-x) instance. It connects to the web UI, authenticates, and either live-tails the log over the UI's Socket.IO stream or pulls historical lines over REST. It is meant for plugin development and debugging.
+
+It is available two ways: as the `hblog` command-line bin, and as the importable `HomebridgeLogClient` API.
+
+### Command line
+
+```
+hblog [filters] [options]
+
+Connection:
+  --host <host>          The homebridge-config-ui-x host (default: localhost).
+  --port <port>          The server port (default: 8581).
+  --tls                  Connect over TLS (https/wss).
+  --user <username>      The login username.
+  --pass <password>      The login password.
+  --token <token>        A pre-acquired bearer token (used verbatim).
+  --otp <code>           A one-time passcode for a 2FA-enabled account.
+
+Mode:
+  -f, --follow           Live-tail the log (default).
+  -n, --lines <N>        Retrieve the most recent N lines.
+  --all                  Retrieve the entire log (cannot be combined with -n).
+
+Filters:
+  -p, --plugin <name>    Only show lines from this plugin (repeatable).
+  -g, --grep <regex>     Only show lines whose message matches this regular expression.
+  -l, --level <level>    Only show lines at this level: debug, error, info, success, warn (repeatable).
+
+Output:
+  --json                 Emit one JSON record per line (NDJSON).
+  --raw                  Emit raw lines with ANSI escapes preserved.
+  --no-color             Strip ANSI escapes from the output.
+  --version              Print the hblog version and exit.
+  -h, --help             Print this help and exit.
+```
+
+Bare `hblog` live-tails the log. `--follow` rides the UI's Socket.IO stream - it is cheap and incremental, includes a free ~500-line seed of recent history, and reconnects automatically through the Homebridge restarts you do while iterating. A deep `-n N` or `--all` falls back to a one-shot whole-file download, paid only when you explicitly ask for history beyond the seed. `history`/`--all` require the Homebridge log method to be file-backed (`file`/`native`); with `systemd`/`custom` there is no file to download, so use `--follow` instead.
+
+Output discipline is pipe-friendly: log data goes to stdout (so `--json` NDJSON stays clean), diagnostics and warnings go to stderr, and a broken downstream pipe (`hblog -f | grep -m1 ...`) ends cleanly. Exit codes are `0` for success (including a clean Ctrl-C), `1` for a connection or authentication failure, and `2` for a usage error.
+
+### `~/.hblog.json`
+
+Connection settings are resolved with the precedence flags > environment > config file > defaults. The environment variables are `HBLOG_HOST`, `HBLOG_PORT`, `HBLOG_USER`, `HBLOG_PASS`, `HBLOG_TOKEN`, and `HBLOG_OTP`. The optional config file lives at `~/.hblog.json` (override the path with `HBLOG_CONFIG`) and carries any subset of these keys:
+
+```json
+{
+  "host": "localhost",
+  "port": 8581,
+  "tls": false,
+  "username": "admin",
+  "password": "your-password",
+  "token": "a-pre-acquired-bearer-token"
+}
+```
+
+A missing file is silent, a malformed file is a clear error, and unknown keys are ignored. The file has no `otp` key on purpose - a one-time passcode is single-use and time-bound, so it only ever comes from `--otp` or `HBLOG_OTP`.
+
+> **Credential security.** `~/.hblog.json` may store a password or a long-lived token in plaintext. Restrict it to your account with `chmod 600 ~/.hblog.json`; `hblog` prints a one-line warning if the file is readable by group or other. Tokens are never logged, and any token embedded in a URL or error message is redacted before it is printed.
+
+### `FORCE_COLOR` and level filtering
+
+In `homebridge-config-ui-x`, a log line's severity is conveyed only by its ANSI color, not by a textual label - and that color is usually absent when Homebridge runs under hb-service/systemd. Reliable `--level` filtering therefore requires color to be present: set `FORCE_COLOR=1` on the **Homebridge process** so it emits colored output. When a `--level` filter is active but the lines carry no color, `hblog` warns once and passes lines through unfiltered by level rather than producing silent empty output.
+
+### Programmatic use
+
+```ts
+import { HomebridgeLogClient } from "homebridge-plugin-utils";
+
+await using client = new HomebridgeLogClient({ credentials: { kind: "password", password: "secret", username: "admin" }, host: "localhost" });
+
+await using stream = client.tail({ mode: "follow-history", quantity: 200 });
+
+for await (const record of stream) {
+
+  process.stdout.write(record.raw + "\n");
+}
+```
+
+`HomebridgeLogClient` is `AsyncDisposable`: `await using` (or an early `break` out of the iteration) tears the underlying transport down with no leak. Its three channels - `history()`, `follow()`, and `tail()` - each return a `LogStream` of parsed `LogRecord`s. Filtering is consumer-composed via `createLogFilter` over any stream.
+
+## Plugin Tooling (`prepare-ui` and `prepare-docs`)
+
+Installing this library also installs a `homebridge-plugin-utils` command-line tool that automates the two build steps every consuming plugin needs: mirroring the compiled webUI into the plugin, and keeping the Feature Options reference in sync with the catalog. Both are meant to run from a plugin's `build` or `prepublishOnly` script so neither artifact can drift from the source.
+
+```
+Usage: homebridge-plugin-utils <command> [options]
+
+Commands:
+  prepare-ui <destination>                          Mirror HBPU's webUI into the plugin's lib directory.
+  prepare-docs <catalog-module> [--doc <path>]      Generate the Feature Options reference into the plugin's docs.
+```
+
+- **`prepare-ui <destination>`** mirrors this library's compiled browser-side webUI into your plugin's UI directory (typically `homebridge-ui/public/lib`) under a content-hashed, version-named subfolder. Because the folder name changes whenever its contents change, the browser's HTTP cache invalidates structurally - you never have to chase a stale cached copy after a rebuild. The run is idempotent and sweeps away the previous build's subfolder in the same pass, while leaving any non-versioned files in the destination untouched.
+
+- **`prepare-docs <catalog-module> [--doc <path>]`** regenerates your plugin's Feature Options reference straight from its options catalog, splicing it into a marked region of the target document - `docs/FeatureOptions.md` by default, or the `--doc` path you pass for a plugin that ships its reference elsewhere. Running it on every build keeps the published reference from drifting away from the options you actually ship.
+
+## Lint Configuration
+
+Plugins that extend `homebridge-plugin-utils/eslint` automatically inherit a small set of in-house ESLint rules under the `@hjdhjd` namespace. Most are stylistic warnings; one (`@hjdhjd/comment-style`) is an enforcement rule wired at error severity to keep comments grep-able and rendering-stable across editors, terminals, diff tools, and review UIs.
+
+### `@hjdhjd/comment-style`
+
+The rule walks every `//` and `/* */` comment in a single pass and reports four classes of drift. Each class autofixes mechanically under `eslint --fix`.
+
+| Group | Pattern | Autofix |
+|---|---|---|
+| A | Unicode glyphs with direct ASCII equivalents: left-right arrow (U+2194), rightwards arrow (U+2192), leftwards arrow (U+2190), less-than-or-equal (U+2264), greater-than-or-equal (U+2265), plus-minus (U+00B1) | Substituted with `<->`, `->`, `<-`, `<=`, `>=`, `+/-` respectively |
+| B | Em-dash (U+2014) | Substituted with a regular hyphen `-` |
+| C | Decorative banner separators in line comments: runs of four or more `=`, `-`, or `#` on a line by themselves | The entire offending source line is removed, including its trailing newline |
+| D | Box-drawing characters: the full Unicode Box Drawing block (U+2500..U+257F), covering both single-line and double-line forms | The offending characters are stripped from the comment |
+
+The rule is comment-scoped by construction. It walks the AST's comment list and cannot touch string literals, template positions, or identifier names, so a webUI label that legitimately renders an arrow to the user, or a test fixture exercising em-dash rendering, is never affected.
+
+For the rare case where a comment must contain one of these characters - documentation that quotes a banned glyph by name, a unit test for the rule itself, or a generated comment that references an external character set - use ESLint's standard inline disable directive on the line above:
+
+```js
+// eslint-disable-next-line @hjdhjd/comment-style
+// Renders the user-visible right-arrow glyph: →
+```
+
+For multiple consecutive lines, wrap the region with `/* eslint-disable @hjdhjd/comment-style */` and `/* eslint-enable @hjdhjd/comment-style */` block directives.
 
 ## Plugin Development Dashboard
 This is mostly of interest to the true developer nerds amongst us.

package/build/eslint-plugin/README.md

@@ -0,0 +1,164 @@
+# `@hjdhjd` ESLint plugin
+
+A self-contained ESLint flat-config plugin bundled inside `homebridge-plugin-utils`. Provides five custom rules and an opinionated flat-config builder
+tuned for Homebridge plugin development - TypeScript backend, JavaScript build tooling, browser-side webUI - all in one consistent rule surface.
+
+## Quick start
+
+The repo's root `eslint.config.mjs` consumes the plugin through its config helper:
+
+```js
+import hbPluginUtils from "./build/eslint-plugin/index.mjs";
+
+export default hbPluginUtils({
+
+  ts: [ "src/**/*.ts" ],
+  js: [ "build/**/*.mjs", "eslint.config.mjs" ],
+  ui: [ "ui/**/*.@(js|mjs)" ]
+});
+```
+
+That single call returns a complete flat-config array: TypeScript rules scoped to `.ts` files, JavaScript rules scoped to `.mjs` files, the common
+`@hjdhjd/*` and `@stylistic/*` rule set applied everywhere, and webUI globals scoped to UI files.
+
+## File layout
+
+```
+build/eslint-plugin/
+├── README.md                                       # this file
+├── index.mjs                                       # public surface: re-exports plugin + config
+├── plugin.mjs                                      # the ESLint plugin object: { meta, rules }
+├── config.mjs                                      # opinionated flat-config builder and rule presets
+├── test-setup.mjs                                  # shared RuleTester scaffold for the rule test suites
+└── rules/
+    ├── blank-line-after-open-brace.mjs             # @hjdhjd/blank-line-after-open-brace
+    ├── blank-line-after-open-brace.test.mjs        # co-located RuleTester suite
+    ├── comment-style.mjs                           # @hjdhjd/comment-style
+    ├── comment-style.test.mjs                      # co-located RuleTester suite
+    ├── enforce-node-protocol.mjs                   # @hjdhjd/enforce-node-protocol
+    ├── enforce-node-protocol.test.mjs              # co-located RuleTester suite
+    ├── paren-comparisons-in-logical.mjs            # @hjdhjd/paren-comparisons-in-logical
+    ├── paren-comparisons-in-logical.test.mjs       # co-located RuleTester suite
+    ├── split-type-imports.mjs                      # @hjdhjd/split-type-imports
+    └── split-type-imports.test.mjs                 # co-located RuleTester suite
+```
+
+Each `rules/*.mjs` file is the full unit for one rule: copyright header, module-level constants, pure helpers, rule header comment, rule object, default
+export. Tests for a rule live in `<rule-name>.test.mjs` alongside it. The two layers above the rules - `plugin.mjs` (what the plugin IS) and `config.mjs`
+(what the plugin RECOMMENDS) - are cleanly separated so a consumer can use the rules without inheriting the opinions, or use the opinions without
+reaching into rule internals.
+
+## Public surface
+
+`index.mjs` exposes the package's full API as re-exports:
+
+| Export | From | What it is |
+|---|---|---|
+| `default` / `config` | `config.mjs` | The flat-config builder function. Takes file-glob options, returns an array suitable for `export default` in `eslint.config.mjs`. |
+| `plugin` | `plugin.mjs` | The ESLint plugin object - `{ meta, rules }`. Drop into a flat config block under `plugins["@hjdhjd"]`. |
+| `plugins` | `config.mjs` | The composed plugin namespace map - `@hjdhjd`, `@stylistic`, `@typescript-eslint`. |
+| `commonRules` | `config.mjs` | Rule preset applied to every linted file regardless of language. |
+| `tsRules` | `config.mjs` | TypeScript-specific rule preset. |
+| `jsRules` | `config.mjs` | JavaScript-specific rule preset. |
+| `globalsUi` | `config.mjs` | Browser-environment globals dictionary for webUI files. |
+
+Every named export has JSDoc on its source declaration.
+
+## The rules
+
+Each rule is described in detail by its own file's header comment. One-line summaries:
+
+| Rule | Purpose |
+|---|---|
+| `@hjdhjd/blank-line-after-open-brace` | Require a blank line after an opening brace when the brace is followed by a newline and the next line carries non-whitespace content. Covers block statements, class bodies, object expressions, and TypeScript interface/type-literal bodies. |
+| `@hjdhjd/comment-style` | Enforce ASCII-first comment style. Substitutes Unicode arrows/comparison glyphs/em-dash with ASCII equivalents, removes decorative banner separators, and strips characters from the Unicode Box Drawing block. |
+| `@hjdhjd/enforce-node-protocol` | Require the `node:` protocol prefix on every reference to a Node.js built-in module. |
+| `@hjdhjd/paren-comparisons-in-logical` | Require parentheses around any comparison operand that is a direct child of a compound `&&` or `||` expression. |
+| `@hjdhjd/split-type-imports` | Require type imports and re-exports to live in declaration-level `import type` / `export type` statements rather than as inline specifier-level `type` qualifiers. Pairs with `@typescript-eslint/consistent-type-imports` configured with `fixStyle: "separate-type-imports"` to express the split-form policy as a single source of truth. |
+
+## Plugin shape
+
+`plugin.mjs` exports the standard ESLint plugin shape:
+
+```js
+{
+  meta: { name: "@hjdhjd/eslint-rules", version: <package.json version> },
+  rules: { /* the five rules above */ }
+}
+```
+
+The version is sourced from the host package's `package.json` via the ECMAScript `import attributes` syntax (`with { type: "json" }`), so it auto-syncs
+with the package version on release.
+
+## Architecture conventions
+
+The plugin follows a few intentional conventions that make it predictable to extend and to read:
+
+- **One rule per file under `rules/`.** Each rule file is self-contained: its constants, pure helpers, rule header, rule object, and default export all
+  live in one place. Helpers are private to the rule's file - cross-rule shared utilities are deliberately avoided to prevent premature abstractions.
+
+- **Pure helpers at module scope, taking dependencies as parameters.** A helper that needs `sourceCode` takes it as its first argument rather than
+  closing over it. The function signature tells the truth about what the helper uses, and the helpers are reachable for unit-testing in isolation if
+  needed.
+
+- **The rule's `create(context)` body stays minimal.** It reads options from `context`, sets up the thin reporter wrapper, and declares its visitors.
+  All real logic lives in the module-level helpers above.
+
+- **Three-part rule header comment on every rule.** What the rule enforces (one sentence), what cases it covers (enumerated), and any non-obvious
+  design decisions. Open any rule file and the first comment block tells you everything you need to know.
+
+- **Tests co-located with rules.** A rule's `RuleTester` suite lives in `<rule-name>.test.mjs` next to the rule file. Matches the convention used
+  throughout `src/` in the host package.
+
+- **Plugin meta in standard ESLint shape.** `meta.name` plus `meta.version` so the plugin is identifiable to ESLint's cache invalidation, the lint
+  output, and any tooling that inspects loaded plugins.
+
+## Adding a new rule
+
+1. Create `rules/<new-rule-name>.mjs` with:
+   - Copyright header.
+   - Module-level constants and pure helpers for the rule.
+   - The three-part rule header comment.
+   - The rule object as a `const`, with default export.
+
+2. Create `rules/<new-rule-name>.test.mjs` co-located alongside, importing `RuleTester` from the shared `../test-setup.mjs` scaffold:
+
+   ```js
+   import { RuleTester } from "../test-setup.mjs";
+   import rule from "./<new-rule-name>.mjs";
+
+   const ruleTester = new RuleTester(/* optional languageOptions */);
+
+   ruleTester.run("<new-rule-name>", rule, { invalid: [ /* ... */ ], valid: [ /* ... */ ] });
+   ```
+
+   Cover every case the rule's header documents under "Cases covered" plus negative passthrough cases that prove the canonical form is ignored.
+
+3. In `plugin.mjs`, add one `import` line and one entry to the `rules` map (alphabetical).
+
+4. If the rule should be enabled by default, add one line to the appropriate preset in `config.mjs`: `commonRules` (applies to every linted file), `tsRules` (TypeScript-only), or `jsRules` (JavaScript-only).
+
+That's the whole motion. No other files need to change.
+
+## Composing with downstream consumers
+
+The `config()` helper is the primary API for consumers who want the full opinionated stack. For consumers who want only the plugin's rules without
+the opinions, import `plugin` from `index.mjs` and wire it into their own flat config directly:
+
+```js
+import { plugin } from "homebridge-plugin-utils/build/eslint-plugin/index.mjs";
+
+export default [{
+
+  plugins: { "@hjdhjd": plugin },
+
+  rules: {
+
+    "@hjdhjd/comment-style": "error",
+    "@hjdhjd/split-type-imports": "warn"
+  }
+}];
+```
+
+The plugin is namespace-agnostic - register it under any name you like in `plugins:` and reference the rules under that prefix. The `@hjdhjd/` namespace
+in `commonRules` is wired to match the bundled defaults; if you re-namespace the plugin in your own config, you'll also need to remap the rule names.

package/build/eslint-plugin/config.mjs

@@ -0,0 +1,308 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * config.mjs: Opinionated ESLint flat-config builder. Composes the `@hjdhjd` plugin together with the project's rule presets for TypeScript, JavaScript,
+ * and browser-UI files.
+ */
+import eslintJs from "@eslint/js";
+import plugin from "./plugin.mjs";
+import stylistic from "@stylistic/eslint-plugin";
+import ts from "typescript-eslint";
+
+// Extract rules by name from a typescript-eslint config array. Throws if the named entry is missing so that a typescript-eslint version bump that renames
+// config entries fails loudly rather than silently dropping rules.
+function configRules(configs, name) {
+
+  const entry = configs.find((c) => c.name === name);
+
+  if(!entry) {
+
+    throw new Error("typescript-eslint config entry not found: " + name);
+  }
+
+  return entry.rules;
+}
+
+/**
+ * The ESLint plugin namespace map used by the composed configuration: `@hjdhjd` (this package's rules), `@stylistic` (the official stylistic-rules
+ * plugin), and `@typescript-eslint`. Drop this object into the `plugins` slot of a flat config block to register every plugin namespace this preset
+ * composes at once.
+ *
+ * The type annotation is deliberately loose since consumers that read the named `plugins` export do their own narrowing before touching rule entries.
+ * It's annotated explicitly so the emitted type stays portable - the raw inference picks up typescript-eslint's exported `CompatiblePlugin` shape,
+ * and the `tsconfig.eslint-plugin.json` declaration-only build (TS2742) refuses to serialize it into the `.d.ts` without citing a deep module path.
+ *
+ * @type {Record<string, { meta?: { name: string; version?: string }; rules?: Record<string, unknown> }>}
+ */
+const plugins = {
+
+  "@hjdhjd": plugin,
+  "@stylistic": stylistic,
+  "@typescript-eslint": ts.plugin
+};
+
+/**
+ * Rule preset for TypeScript source files. Builds on `typescript-eslint`'s strict and stylistic type-checked configs, then layers project-specific
+ * overrides: type-aware lint rules (`await-thenable`, `no-floating-promises`, `prefer-nullish-coalescing`, etc.) at warn level, explicit return-type and
+ * module-boundary requirements, and `@stylistic/member-delimiter-style`. Disables the JavaScript-recommended versions of rules that have TypeScript-aware
+ * equivalents to avoid double-flagging.
+ *
+ * Deliberately omits `@typescript-eslint/promise-function-async` and forces `@typescript-eslint/require-await` (and the base `require-await`) off. The pair
+ * encodes a tight coupling between Promise return types and the `async` keyword that predates the Disposable protocol: `[Symbol.asyncDispose]()` must be declared
+ * `async ...(): Promise<void>` to satisfy `await using` even when the body is synchronous, and identity-preserving Promise pass-throughs (e.g., `markHandled` in
+ * `src/util.ts`) cannot be marked `async` without wrapping the return in a fresh chain and breaking reference equality. Encoding the stance at the preset level
+ * rather than scattering per-site `eslint-disable` directives is the SSOT.
+ *
+ * Spread into the `rules:` slot of a flat config block scoped to `.ts` files.
+ */
+const tsRules = {
+
+  ...configRules(ts.configs.strictTypeChecked, "typescript-eslint/strict-type-checked"),
+  ...configRules(ts.configs.stylisticTypeChecked, "typescript-eslint/stylistic-type-checked"),
+  "@stylistic/member-delimiter-style": "warn",
+  "@typescript-eslint/await-thenable": "warn",
+  "@typescript-eslint/consistent-type-imports": [ "warn", { "fixStyle": "separate-type-imports", "prefer": "type-imports" } ],
+  "@typescript-eslint/explicit-function-return-type": "warn",
+  "@typescript-eslint/explicit-module-boundary-types": "warn",
+  "@typescript-eslint/no-confusing-void-expression": [ "error", { "ignoreArrowShorthand": true, "ignoreVoidOperator": true,
+    "ignoreVoidReturningFunctions": true } ],
+  "@typescript-eslint/no-explicit-any": "warn",
+  "@typescript-eslint/no-floating-promises": [ "warn", { "ignoreIIFE": true } ],
+  "@typescript-eslint/no-non-null-assertion": "warn",
+  "@typescript-eslint/no-unnecessary-condition": "warn",
+  "@typescript-eslint/no-unused-expressions": "warn",
+  "@typescript-eslint/no-unused-vars": [ "warn", { "argsIgnorePattern": "^_", "caughtErrors": "all", "caughtErrorsIgnorePattern": "^_", "varsIgnorePattern": "^_" } ],
+  "@typescript-eslint/prefer-nullish-coalescing": "warn",
+  "@typescript-eslint/require-await": "off",
+  "no-dupe-class-members": "off",
+  "no-redeclare": "off",
+  "no-undef": "off",
+  "no-unused-expressions": "off",
+  "no-unused-vars": "off",
+  "require-await": "off"
+};
+
+/**
+ * Rule preset for JavaScript source files. Starts from `typescript-eslint`'s `disableTypeChecked` set (so type-aware rules don't fire on plain JS), then
+ * re-enables `no-unused-vars` with the underscore-prefix ignore pattern. The `require-await` rule is left disabled here for the same reason the TypeScript
+ * preset omits its pair - see the omission paragraph in the {@link tsRules} JSDoc.
+ *
+ * Spread into the `rules:` slot of a flat config block scoped to `.js` / `.mjs` files.
+ */
+const jsRules = {
+
+  ...ts.configs.disableTypeChecked.rules,
+
+  // Restates the "off" value that `disableTypeChecked` already assigns to this rule.
+  "@typescript-eslint/no-floating-promises": "off",
+  "no-unused-vars": [ "warn", { "argsIgnorePattern": "^_", "caughtErrors": "all", "caughtErrorsIgnorePattern": "^_", "varsIgnorePattern": "^_" } ]
+};
+
+/**
+ * Rule preset applied to every linted file regardless of language. Disables the base ESLint rules that are redundant once TypeScript's own compiler
+ * and syntax already catch the same errors, mirroring the `typescript-eslint` compatibility overlay it spreads in; the enabled ESLint-recommended
+ * baseline itself comes from the separate `eslintJs.configs.recommended` block pushed in {@link config}. Layers on top of that the full `@hjdhjd/*`
+ * rule set, the `@stylistic/*` whitespace and formatting rules, and the project's opinionated `sort-imports` / `sort-keys` / `quotes` / `eqeqeq` /
+ * `curly` constraints.
+ *
+ * Spread into the `rules:` slot of the all-files block of a flat config.
+ */
+const commonRules = {
+
+  ...ts.configs.eslintRecommended.rules,
+  "@hjdhjd/blank-line-after-open-brace": "warn",
+  "@hjdhjd/comment-style": "error",
+  "@hjdhjd/enforce-node-protocol": "warn",
+  "@hjdhjd/paren-comparisons-in-logical": "warn",
+  "@hjdhjd/split-type-imports": "warn",
+  "@stylistic/array-bracket-spacing": [ "warn", "always", { "arraysInArrays": true, "objectsInArrays": true, "singleValue": false } ],
+  "@stylistic/block-spacing": "warn",
+  "@stylistic/brace-style": [ "warn", "1tbs", { "allowSingleLine": true } ],
+  "@stylistic/comma-dangle": "warn",
+  "@stylistic/eol-last": [ "warn", "always" ],
+  "@stylistic/generator-star-spacing": "warn",
+  "@stylistic/implicit-arrow-linebreak": "warn",
+  "@stylistic/indent": [ "warn", 2, { "SwitchCase": 1 } ],
+  "@stylistic/keyword-spacing": [ "warn",
+    { "overrides": { "for": { "after": false }, "if": { "after": false }, "switch": { "after": false }, "while": { "after": false } } } ],
+  "@stylistic/linebreak-style": [ "warn", "unix" ],
+  "@stylistic/lines-between-class-members": [ "warn", "always", { "exceptAfterSingleLine": true } ],
+  "@stylistic/max-len": [ "warn", 170 ],
+  "@stylistic/no-tabs": "warn",
+  "@stylistic/no-trailing-spaces": "warn",
+  "@stylistic/operator-linebreak": [ "warn", "after", { "overrides": { ":": "after", "?": "after" } } ],
+  "@stylistic/padding-line-between-statements": [ "warn",
+
+    // Require a blank line before every statement type in next.
+    { "blankLine": "always", "next": [ "break", "case", "class", "continue", "default", "export", "for", "function", "if", "import", "return" ], "prev": "*" },
+
+    // Require blank lines after every statement type in prev.
+    { "blankLine": "always", "next": "*", "prev": [ "const", "directive", "let", "var" ] },
+
+    // Multiple sequential case declarations may be grouped together.
+    { "blankLine": "any", "next": [ "case", "default" ], "prev": [ "case", "default" ] },
+
+    // Multiple sequential variable declarations may be grouped together.
+    { "blankLine": "any", "next": [ "const", "let", "var" ], "prev": [ "const", "let", "var" ] },
+
+    // Multiple sequential export declarations may be grouped together.
+    { "blankLine": "any", "next": "export", "prev": "export" },
+
+    // Multiple sequential import declarations must be grouped together.
+    { "blankLine": "never", "next": "import", "prev": "import" },
+
+    // Multiple sequential directive prologues must be grouped together.
+    { "blankLine": "never", "next": "directive", "prev": "directive" }
+  ],
+  "@stylistic/semi": [ "warn", "always" ],
+  "@stylistic/space-before-function-paren": [ "warn", { "anonymous": "never", "asyncArrow": "always", "catch": "never", "named": "never" } ],
+  "@stylistic/space-in-parens": "warn",
+  "@stylistic/space-infix-ops": "warn",
+  "@stylistic/space-unary-ops": "warn",
+  "@typescript-eslint/dot-notation": [ "warn", { "allowIndexSignaturePropertyAccess": true } ],
+  "@typescript-eslint/no-this-alias": "warn",
+  "camelcase": "warn",
+  "curly": [ "warn", "all" ],
+  "dot-notation": "off",
+  "eqeqeq": "warn",
+  "logical-assignment-operators": [ "warn", "always", { "enforceForIfStatements": true } ],
+  "no-await-in-loop": "warn",
+  "no-console": "warn",
+  "no-restricted-syntax": [ "warn", "TemplateLiteral" ],
+  "prefer-arrow-callback": "warn",
+  "prefer-const": "warn",
+  "quotes": [ "warn", "double", { "allowTemplateLiterals": false, "avoidEscape": false } ],
+  "sort-imports": "warn",
+  "sort-keys": "warn",
+  "sort-vars": "warn"
+};
+
+/**
+ * Browser-environment globals typically present in Homebridge webUI files - `window`, `document`, `fetch`, the Homebridge configuration API entry
+ * point, and a few timer functions. Each is declared as `"readonly"` so `no-undef` accepts references without permitting reassignment.
+ *
+ * Pass into the `languageOptions.globals` slot of a flat config block scoped to UI files.
+ */
+const globalsUi = Object.fromEntries([ "clearTimeout", "console", "container", "document", "fetch", "getComputedStyle", "homebridge", "setTimeout", "window" ]
+  .map((key) => [ key, "readonly" ]));
+
+/**
+ * Build a ready-to-use ESLint flat config array. Consumers call this function and export default the result.
+ *
+ * Every option is optional and defaults to an empty array, mirrored by the destructuring defaults in the signature below. The JSDoc marks them optional with the
+ * bracket form so the emitted declaration types each property as optional, matching how consumers actually call this - passing only the subset they need.
+ *
+ * @param {object} [options] - Configuration options.
+ * @param {string[]} [options.ts] - Glob patterns for TypeScript files (strict + stylistic type-checked rules).
+ * @param {string[]} [options.js] - Glob patterns for JavaScript files (disable-type-checked rules).
+ * @param {string[]} [options.ui] - Glob patterns for browser UI files (adds browser globals).
+ * @param {string[]} [options.allowDefaultProject] - Globs passed to parserOptions.projectService.allowDefaultProject.
+ * @param {string[]} [options.ignores] - Global ignore patterns (in addition to the hardcoded "dist" ignore on the common block).
+ * @param {object[]} [options.extraConfigs] - Additional flat config objects appended to the output.
+ * @returns {object[]} A flat config array suitable for `export default` in eslint.config.mjs. Block ordering is significant - do not reorder.
+ */
+function config({
+  allowDefaultProject = [],
+  extraConfigs = [],
+  ignores = [],
+  js = [],
+  ts: tsFiles = [],
+  ui = []
+} = {}) {
+
+  const allFiles = [ ...tsFiles, ...js, ...ui ];
+  const configs = [];
+
+  // Global ignores block.
+  if(ignores.length > 0) {
+
+    configs.push({ ignores });
+  }
+
+  // Core ESLint recommended rules. This block must precede the TS/JS blocks so that their rule overrides (e.g., no-unused-vars: "off") take priority.
+  if(allFiles.length > 0) {
+
+    configs.push(eslintJs.configs.recommended);
+  }
+
+  // TypeScript-specific rules.
+  if(tsFiles.length > 0) {
+
+    configs.push({
+
+      files: tsFiles,
+      rules: { ...tsRules }
+    });
+  }
+
+  // JavaScript-specific rules.
+  if(js.length > 0) {
+
+    configs.push({
+
+      files: js,
+      rules: { ...jsRules }
+    });
+  }
+
+  // Common rules applied to all linted files.
+  if(allFiles.length > 0) {
+
+    configs.push({
+
+      files: allFiles,
+
+      ignores: ["dist"],
+
+      languageOptions: {
+
+        ecmaVersion: "latest",
+        parser: ts.parser,
+        parserOptions: {
+
+          ecmaVersion: "latest",
+
+          projectService: {
+
+            allowDefaultProject,
+            defaultProject: "./tsconfig.json"
+          }
+        },
+
+        sourceType: "module"
+      },
+
+      linterOptions: {
+
+        reportUnusedDisableDirectives: "error"
+      },
+
+      plugins: { ...plugins },
+
+      rules: { ...commonRules }
+    });
+  }
+
+  // UI globals block.
+  if(ui.length > 0) {
+
+    configs.push({
+
+      files: ui,
+
+      languageOptions: {
+
+        globals: { ...globalsUi }
+      }
+    });
+  }
+
+  // Escape hatch for project-specific config blocks.
+  configs.push(...extraConfigs);
+
+  return configs;
+}
+
+export default config;
+
+// Named exports for advanced customization or gradual migration.
+export { commonRules, config, globalsUi, jsRules, plugins, tsRules };

package/build/eslint-plugin/index.mjs

@@ -0,0 +1,7 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * index.mjs: Public surface of the bundled `@hjdhjd` ESLint plugin. Re-exports the plugin object and the opinionated config builder.
+ */
+export { default as plugin } from "./plugin.mjs";
+export { commonRules, config, globalsUi, jsRules, plugins, tsRules } from "./config.mjs";
+export { default } from "./config.mjs";