homebridge-tuya-plus 3.14.0-dev.4 → 3.14.0-dev.40

package/.github/workflows/publish-dev.yml

@@ -1,56 +1,97 @@
-name: Publish dev to npm
+name: Publish to npm (dev + PR test builds)
 
-# Publishes commits on `main` to npm under the `dev` dist-tag.
+# This workflow publishes two kinds of UNSTABLE builds to npm. Stable releases
+# always live on the `latest` dist-tag and are cut manually; nothing here ever
+# touches `latest`.
 #
-# Versioning:
-#   * Dev builds target the NEXT minor release, since releases here are
-#     usually a minor bump. With package.json at e.g. 3.13.0, dev builds
-#     are published as 3.14.0-dev.<run-number> (minor +1, patch reset to 0,
-#     prerelease tag = the GitHub Actions run number). In semver these sort
-#     below the eventual 3.14.0 release, so `latest` always wins once cut.
-#   * Release commits are skipped: if a push changes package.json's version
-#     (i.e. you bumped it to cut a real release and publish to npm
-#     manually), no dev build is published for that push.
+# 1. Dev builds (automatic) — every push to `main`:
+#      * Published under the `dev` dist-tag.
+#      * Versioned as <next-minor>.0-dev.<run-number> (e.g. 3.14.0-dev.42).
+#        package.json at 3.13.0 -> dev builds target 3.14.0. In semver these
+#        sort below the eventual 3.14.0 release, so `latest` always wins.
+#      * Release commits are skipped: if a push changes package.json's version
+#        (you bumped it to cut a real release), no dev build is published.
 #
-# Security model (why a malicious PR cannot steal publishing rights):
-#   * No npm token is stored anywhere. Publishing uses npm Trusted
-#     Publishing (OIDC): GitHub mints a short-lived, cryptographically
-#     signed token that npm only accepts when its claims match THIS repo +
-#     THIS workflow file. There is no durable credential to exfiltrate.
-#   * This workflow never runs on `pull_request`, only on pushes to `main`
-#     (post-merge) and manual dispatch — so fork PRs get nothing.
-#   * The privileged `publish` job is minimal and isolated: it does not
-#     run `npm ci`, a build, or tests, and uses `--ignore-scripts`, so no
-#     repo/dependency code executes while the OIDC permission is present.
-#     Tests run in a separate, unprivileged job that gates publishing, and
-#     the version is computed in an unprivileged `prepare` job.
+# 2. PR test builds (manual) — a maintainer comments `/publish` on a PR:
+#      * Published under a PR-specific `pr-<N>` dist-tag (e.g. pr-57), with a
+#        unique version <next-minor>.0-pr.<N>.<run-number> (e.g. 3.14.0-pr.57.43).
+#      * Lets you install and try an unmerged PR on real hardware without
+#        disturbing `latest` OR `dev`:  npm i -g homebridge-tuya-plus@pr-57
+#      * Cleanup is a token-free local step: run `npm run cleanup:pr-tags` to
+#        delete the `pr-<N>` tags of merged/closed PRs (uses your npm login).
+#        OIDC can't manage dist-tags, so this is intentionally not a CI job.
+#      * Triggered ONLY by someone with push (write) access to the repo — the
+#        owner and any write/maintain/admin collaborator. A drive-by `/publish`
+#        from an outside PR author (no push access) does nothing.
 #
-# One-time setup required for this to succeed (see PR/commit notes):
+# Why a separate `pr-<N>` tag instead of reusing `dev`: `dev` is a moving
+# channel users follow to get "latest main". Publishing unmerged PR code there
+# would feed untested code to everyone on `@dev`. A per-PR tag keeps three clear
+# lanes — `latest` (everyone), `dev` (main followers), `pr-<N>` (that one PR).
+#
+# ---------------------------------------------------------------------------
+# Security model (why a malicious PR cannot steal publishing rights)
+# ---------------------------------------------------------------------------
+#   * No npm token is stored anywhere. Publishing uses npm Trusted Publishing
+#     (OIDC): GitHub mints a short-lived token that npm only accepts when its
+#     claims match THIS repo + THIS workflow file (publish-dev.yml) + the
+#     `npm-dev` environment. There is no durable credential to exfiltrate.
+#   * npm allows only ONE trusted publisher per package, so BOTH paths must run
+#     from this file and use `environment: npm-dev` to authenticate. (The PR
+#     path needs no extra npm/GitHub setup beyond the existing dev config.)
+#   * The `dev` path never runs on `pull_request`; the PR path runs on
+#     `issue_comment`, which always uses the workflow file from `main` — a PR
+#     cannot alter this file to change what runs.
+#   * Untrusted PR code is fenced off from the publishing credential:
+#       - `pr-test` checks out and runs the PR's code (npm ci / lint / test)
+#         but is UNPRIVILEGED: `contents: read`, no secrets, no id-token, and
+#         `persist-credentials: false`. Same blast radius as ordinary fork CI.
+#       - `pr-publish` HOLDS the OIDC permission but runs NO PR code: no
+#         `npm ci`, no build, no tests, and `--ignore-scripts` on both
+#         `npm version` and `npm publish`, so no lifecycle script executes
+#         while the credential is present. It only packs + uploads the tarball.
+#       - The OIDC token is scoped to THIS package, so a PR that renames the
+#         package in package.json cannot hijack a different one (publish fails).
+#       - The head SHA is resolved once, up front, and pinned for every later
+#         job, so a push landed after `/publish` cannot swap in different code.
+#   * Comment/reaction jobs use a write-scoped token but check out NO PR code.
+#
+# ---------------------------------------------------------------------------
+# One-time setup (already in place for the dev path; PR path reuses it):
 #   1. npmjs.com -> package Settings -> Trusted Publisher:
 #        Publisher: GitHub Actions
 #        Organization/user: adrianjagielak
 #        Repository:        homebridge-tuya-plus
 #        Workflow filename: publish-dev.yml
 #        Environment:       npm-dev
-#   2. GitHub repo Settings -> Environments -> create `npm-dev`,
-#      restrict deployment branches to `main` (optional: required reviewer).
+#   2. GitHub repo Settings -> Environments -> `npm-dev`, deployment branches
+#      restricted to `main` (optional: required reviewer). The PR path runs on
+#      `main`'s ref too, so this restriction is satisfied for both paths.
 
 on:
   push:
     branches: [main]
   workflow_dispatch:
+  # Maintainer types `/publish` on a PR to cut a test build of that PR.
+  issue_comment:
+    types: [created]
 
-# Least privilege by default; only the publish job opts into id-token.
+# Least privilege by default; jobs opt into more only where needed.
 permissions:
   contents: read
 
-# Don't cancel an in-flight publish; let each commit publish its version.
+# Serialize per lane, never cancel an in-flight publish: `publish-dev` for the
+# dev path, `publish-pr-<N>` per PR for the PR path (so they don't block).
 concurrency:
-  group: publish-dev
+  group: ${{ github.event_name == 'issue_comment' && format('publish-pr-{0}', github.event.issue.number) || 'publish-dev' }}
   cancel-in-progress: false
 
 jobs:
+  # ===========================================================================
+  # DEV PATH — push to main / manual dispatch. (Behavior unchanged.)
+  # ===========================================================================
   test:
+    if: github.event_name != 'issue_comment'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -65,6 +106,7 @@ jobs:
   # computes the dev version. Kept out of the `publish` job so no extra work
   # runs while the OIDC publishing permission is present.
   prepare:
+    if: github.event_name != 'issue_comment'
     runs-on: ubuntu-latest
     outputs:
       should_publish: ${{ steps.check.outputs.should_publish }}
@@ -113,8 +155,8 @@ jobs:
 
   publish:
     needs: [test, prepare]
-    # Skip release commits (version bumped in this push).
-    if: needs.prepare.outputs.should_publish == 'true'
+    # Dev path only, and skip release commits (version bumped in this push).
+    if: github.event_name != 'issue_comment' && needs.prepare.outputs.should_publish == 'true'
     runs-on: ubuntu-latest
     # Bind this environment in repo Settings to the `main` branch so that
     # only main can ever reach the publish step.
@@ -144,3 +186,228 @@ jobs:
       # --provenance attaches a signed build attestation (needs a public repo).
       - name: Publish (dev tag)
         run: npm publish --tag dev --provenance --ignore-scripts
+
+  # ===========================================================================
+  # PR PATH — maintainer comments `/publish` on a PR. (New.)
+  # ===========================================================================
+
+  # Gate + ack. Runs NO PR code. Verifies the commenter is a maintainer,
+  # resolves & pins the PR head, and reads the version base from trusted `main`.
+  authorize:
+    if: >
+      github.event_name == 'issue_comment' &&
+      github.event.issue.pull_request &&
+      startsWith(github.event.comment.body, '/publish') &&
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # checkout main to read the version base
+      issues: write # react to / comment on the triggering comment
+      pull-requests: write
+    outputs:
+      authorized: ${{ steps.auth.outputs.authorized }}
+      head_sha: ${{ steps.auth.outputs.head_sha }}
+      head_repo: ${{ steps.auth.outputs.head_repo }}
+      pr_number: ${{ steps.auth.outputs.pr_number }}
+      base_version: ${{ steps.basever.outputs.base_version }}
+    steps:
+      - name: Verify maintainer & resolve PR head
+        id: auth
+        uses: actions/github-script@v7
+        with:
+          script: |
+            // Require the command to be exactly `/publish` (optional trailing text).
+            const body = (context.payload.comment.body || '').trim();
+            if (!/^\/publish(?:\s|$)/.test(body)) {
+              core.setOutput('authorized', 'false');
+              return;
+            }
+            // Authorization: the commenter must have PUSH (write) access. The
+            // REST `permission` field uses legacy roles, so `admin`/`write`
+            // covers admin/maintain/write (can push) and excludes triage/read.
+            // This is stricter and truer to intent than author_association (a
+            // COLLABORATOR could be read-only). The job `if` is only a coarse
+            // pre-filter; this API check is the authoritative gate.
+            const username = context.payload.comment.user.login;
+            let canPush = false;
+            try {
+              const { data: perm } = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                username,
+              });
+              canPush = ['admin', 'write'].includes(perm.permission);
+              core.info(`${username} permission: ${perm.permission} (role: ${perm.role_name || 'n/a'})`);
+            } catch (err) {
+              // If the permission API can't be read, fall back to the trusted
+              // author_association set so a maintainer is never locked out. This
+              // still keeps out drive-by PR authors (CONTRIBUTOR / NONE).
+              const assoc = context.payload.comment.author_association;
+              canPush = ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(assoc);
+              core.warning(`Permission API unavailable (${err.status || err.message}); fell back to association ${assoc}.`);
+            }
+            if (!canPush) {
+              core.notice(`Ignoring /publish from ${username}: no push access.`);
+              core.setOutput('authorized', 'false');
+              return;
+            }
+            // Resolve the PR's CURRENT head and pin this exact SHA for every
+            // later job, so a push landed after `/publish` can't swap in code.
+            const { data: pr } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.issue.number,
+            });
+            if (!pr.head.repo) {
+              core.setFailed('PR head repository is unavailable (fork deleted?).');
+              core.setOutput('authorized', 'false');
+              return;
+            }
+            core.setOutput('head_sha', pr.head.sha);
+            core.setOutput('head_repo', pr.head.repo.full_name);
+            core.setOutput('pr_number', String(pr.number));
+            core.setOutput('authorized', 'true');
+            // Acknowledge so the maintainer sees the command was accepted.
+            await github.rest.reactions.createForIssueComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: context.payload.comment.id,
+              content: 'eyes',
+            });
+
+      # Version base comes from TRUSTED main, never the PR's package.json, so an
+      # untrusted PR cannot influence the published version.
+      - name: Checkout main (trusted)
+        if: steps.auth.outputs.authorized == 'true'
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Compute version base from main
+        id: basever
+        if: steps.auth.outputs.authorized == 'true'
+        run: |
+          NEXT="$(node -e "const v=require('./package.json').version.split('.'); v[1]=Number(v[1])+1; v[2]=0; console.log(v.join('.'))")"
+          echo "base_version=$NEXT" >> "$GITHUB_OUTPUT"
+          echo "Version base (from main): $NEXT"
+
+  # Unprivileged gate: runs the PR's code. No secrets, read-only token, no
+  # id-token, no persisted git credentials — same trust level as fork CI.
+  pr-test:
+    needs: authorize
+    if: needs.authorize.outputs.authorized == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ needs.authorize.outputs.head_repo }}
+          ref: ${{ needs.authorize.outputs.head_sha }}
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run test
+
+  # Privileged publish. Holds the OIDC permission but runs NO PR code: no
+  # npm ci, no build, no tests; --ignore-scripts on version + publish.
+  pr-publish:
+    needs: [authorize, pr-test]
+    if: needs.authorize.outputs.authorized == 'true'
+    runs-on: ubuntu-latest
+    # Must match the trusted publisher's environment (npm allows one publisher
+    # per package). issue_comment runs on main's ref, so a main-only branch
+    # restriction on this environment is satisfied.
+    environment: npm-dev
+    permissions:
+      contents: read
+      id-token: write # OIDC -> npm Trusted Publishing (no stored token)
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+      tag: ${{ steps.ver.outputs.tag }}
+    steps:
+      # The PR's code — but we never execute it (see --ignore-scripts below).
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ needs.authorize.outputs.head_repo }}
+          ref: ${{ needs.authorize.outputs.head_sha }}
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      # Trusted Publishing (OIDC) requires npm >= 11.5.1.
+      - name: Ensure OIDC-capable npm
+        run: npm install -g npm@latest
+
+      # Unique, immutable version + a PR-specific dist-tag. Base comes from main
+      # (via authorize), so the PR's package.json cannot influence versioning.
+      - name: Compute PR build version + tag
+        id: ver
+        env:
+          BASE: ${{ needs.authorize.outputs.base_version }}
+          PR: ${{ needs.authorize.outputs.pr_number }}
+        run: |
+          VERSION="${BASE}-pr.${PR}.${GITHUB_RUN_NUMBER}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=pr-${PR}" >> "$GITHUB_OUTPUT"
+          echo "Will publish $VERSION under dist-tag pr-${PR}"
+
+      # Writes package.json on the runner only; --ignore-scripts so no PR
+      # version/preversion/postversion hook runs with the credential present.
+      - name: Set version
+        run: npm version "${{ steps.ver.outputs.version }}" --no-git-tag-version --allow-same-version --ignore-scripts
+
+      # Published under pr-<N>, NEVER latest/dev. No NODE_AUTH_TOKEN: npm
+      # exchanges the OIDC id-token for a short-lived, package-scoped credential.
+      # --ignore-scripts ensures no PR lifecycle script runs with that credential.
+      - name: Publish (pr-<N> tag)
+        run: npm publish --tag "${{ steps.ver.outputs.tag }}" --provenance --ignore-scripts
+
+  # Report the outcome back on the PR. Runs NO PR code.
+  notify:
+    needs: [authorize, pr-publish]
+    if: always() && needs.authorize.outputs.authorized == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/github-script@v7
+        env:
+          PUBLISH_RESULT: ${{ needs.pr-publish.result }}
+          PR_NUMBER: ${{ needs.authorize.outputs.pr_number }}
+          HEAD_SHA: ${{ needs.authorize.outputs.head_sha }}
+          VERSION: ${{ needs.pr-publish.outputs.version }}
+          TAG: ${{ needs.pr-publish.outputs.tag }}
+        with:
+          script: |
+            const { PUBLISH_RESULT, PR_NUMBER, HEAD_SHA, VERSION, TAG } = process.env;
+            const issue_number = Number(PR_NUMBER);
+            const comment_id = context.payload.comment.id;
+            const { owner, repo } = context.repo;
+            const runUrl = `${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`;
+            if (PUBLISH_RESULT === 'success') {
+              const sha = (HEAD_SHA || '').slice(0, 7);
+              const body = [
+                `🚀 Published **\`${TAG}\`** for testing — commit \`${sha}\`.`,
+                ``,
+                '```sh',
+                `npm install -g homebridge-tuya-plus@${TAG}`,
+                '```',
+                `Exact version: \`${VERSION}\``,
+              ].join('\n');
+              await github.rest.issues.createComment({ owner, repo, issue_number, body });
+              await github.rest.reactions.createForIssueComment({ owner, repo, comment_id, content: 'rocket' });
+            } else {
+              await github.rest.issues.createComment({
+                owner, repo, issue_number,
+                body: `❌ \`/publish\` did not complete — the build, tests, or publish step failed. See the [run logs](${runUrl}).`,
+              });
+              await github.rest.reactions.createForIssueComment({ owner, repo, comment_id, content: 'confused' });
+            }

package/AGENTS.md

@@ -0,0 +1,162 @@
+# AGENTS.md
+
+Guidance for AI coding agents (Claude Code, Codex, etc.) working in this
+repository. Human contributors may find it useful too.
+
+## What this project is
+
+`homebridge-tuya-plus` is a community-maintained [Homebridge](https://homebridge.io)
+plugin that exposes Tuya smart-home devices to Apple HomeKit. It is
+**LAN-first**: virtually every device is controlled locally over Tuya's LAN
+protocol (faster, more private, works without internet). A small, strictly
+opt-in **Tuya Cloud** path exists only for hardware that genuinely cannot be
+reached on the LAN (e.g. battery-powered "sleepy" irrigation timers).
+
+It is published to npm and installed by end users into their Homebridge setups,
+many of whom already have devices paired with HomeKit. **Treat it as production
+software with a large existing install base.**
+
+## Tech stack & layout
+
+- **Node.js, CommonJS** (`require`/`module.exports`). No TypeScript, no build
+  step — the source that ships is the source in the repo.
+- Target runtimes: Node `^20.18 || ^22.10 || ^24`, Homebridge `^1.8 || ^2.0`
+  (see `engines` in `package.json`). Keep changes compatible with both
+  Homebridge 1.x and 2.x.
+
+```
+index.js          Platform entry point. Registers the TuyaLan platform,
+                  maps config "type" -> accessory class (CLASS_DEF), runs
+                  discovery, and creates/reuses cached HomeKit accessories.
+lib/
+  BaseAccessory.js  Shared base class for all accessories (state helpers,
+                    unit/color conversions, getCategory()).
+  *Accessory.js     One class per device type (lights, fans, garage doors,
+                    irrigation, AC, blinds, ...). Each extends BaseAccessory.
+  TuyaAccessory.js  The LAN protocol implementation (framing, encryption,
+                    discovery, reconnection) for protocol versions 3.1-3.5+.
+  TuyaDiscovery.js  UDP broadcast discovery of devices on the LAN.
+  TuyaCloud*.js     Opt-in Tuya Cloud client (OpenAPI + MQTT realtime).
+bin/              Standalone CLI helpers (tuya-lan*, key discovery/decode).
+test/             Jest unit tests; shared HAP mocks in test/support/mocks.js.
+scripts/          Maintenance scripts (e.g. PR-tag cleanup).
+wiki/             User-facing docs (device setup, cloud setup, mappings).
+config.schema.json  Drives the Homebridge Config UI X settings form.
+```
+
+## Commands
+
+```bash
+npm ci          # install (CI uses this; lockfile is committed)
+npm test        # Jest unit tests — keep these green
+npm run lint    # ESLint (flat config in eslint.config.mjs)
+```
+
+CI runs `npm test` and `npm run lint` on every pull request to `main`. Run both
+locally before you consider a change done.
+
+## How an accessory works
+
+When adding or changing a device type, follow the existing pattern:
+
+1. Create `lib/<Name>Accessory.js` extending `BaseAccessory`.
+2. Implement `static getCategory(Categories)` returning a real HAP category
+   constant (don't leave the `OTHER` fallback unless truly generic).
+3. Build HomeKit services/characteristics in `_registerCharacteristics(dps)`,
+   which runs once the device reports its first state.
+4. Read/write device data points (DPs) via the `BaseAccessory` helpers
+   (`getState`/`setState`/`setMultiState` and their `*Async` variants) rather
+   than poking `this.device` directly.
+5. Register the type in `CLASS_DEF` in `index.js`.
+6. Add the device's config options to `config.schema.json` so they appear in the
+   Homebridge UI.
+7. Add Jest tests using `makeInstance(...)` from `test/support/mocks.js`.
+
+## Conventions
+
+- **Match the surrounding code.** Mirror the existing file's naming, spacing,
+  quoting (single quotes), and structure. Don't introduce a new style.
+- **Write code that reads clearly without comments.** Prefer descriptive names
+  and straightforward control flow over cleverness.
+- **Comment the "why", not the "what".** Existing comments explain non-obvious
+  protocol quirks, HomeKit/Homebridge gotchas, and decisions that protect
+  backwards compatibility (often citing an issue/PR number). Add comments of
+  that kind where they save the next reader real time; skip narration of obvious
+  code.
+- **Tests where they make sense.** Pure logic (state mapping, value
+  conversions, protocol encode/decode, config coercion) should have Jest tests.
+  The HAP layer is mocked — don't reach for real hardware or the network in
+  tests.
+- ESLint currently disables a few rules (`no-unused-vars`, `no-empty`,
+  `no-prototype-builtins`) as tech debt; don't rely on or expand that. Keep new
+  code clean.
+
+## Logging
+
+Users run this in Homebridge and read these logs; a chatty plugin is a real
+complaint. The bar for a non-debug line is high.
+
+- **`debug` is the default.** Anything routine, per-message, per-state-change,
+  per-connect, or protocol-level (odd/raw/malformed frames, reconnects, socket
+  recycling, DP dumps, "X changed: …") goes to `this.log.debug`. If it can fire
+  more than a handful of times in normal operation, it's `debug`.
+- **`info`/`warn`/`error` are for what the user must see or act on**, and the
+  level must match real severity — a harmless condition (e.g. a cloud-fallback
+  failure while the device is reachable over the LAN) is not a `warn`/`error`.
+  Prefer one actionable line over a vague one; name the device.
+- **Never spam.** A condition that recurs on a timer or hot path must be
+  deduplicated (surface once, then drop repeats to `debug` until it changes) and
+  its retry backed off — see `TuyaCloudDevice._onConnectFailure` and the
+  discovery port-in-use guard for the pattern.
+- **Use the Homebridge logger** (`this.log` / `this.log.debug|info|warn|error`),
+  never `console.*`, in plugin/runtime code. (The standalone `bin/` CLIs are the
+  exception: their `console.*` is intentional user-facing output.)
+- **Logging must never throw and must never leak secrets** — don't dump a whole
+  config/props object (it carries the device's local `key`); log the id/name.
+
+## Backwards compatibility (read before changing behavior)
+
+This is the most important rule in this repo. Users have working setups and
+devices already paired in HomeKit; a careless change can break them silently.
+
+- **Config is a public API.** Don't rename, repurpose, or remove existing config
+  keys (platform- or device-level). Add new options as optional with safe
+  defaults, and keep `config.schema.json` in sync. Be lenient in what you
+  accept (see `_coerceBoolean` / `coerceBoolean`).
+- **Keep cloud strictly opt-in.** LAN remains the default path. Cloud code runs
+  only when a device sets `cloud: true` (or a `cloud` object) and credentials
+  are present. `mqtt` is an optional dependency — don't make it mandatory.
+- **Preserve protocol support.** The plugin speaks Tuya LAN 3.1-3.5 and is
+  forward-compatible with newer versions; don't drop versions or break version
+  routing.
+- When a change must alter behavior, make it opt-in.
+
+## Debug config block
+
+The platform reads an **undocumented** top-level `debug` object from the config
+(see `_debugConfig()` in `index.js`). It holds dev/test-only switches and is
+deliberately **kept out of `config.schema.json`** so it never appears in the
+Homebridge UI. Treat it as the one place such switches belong; add new ones as
+optional, off-by-default flags read through `_debugConfig()` and coerced with
+`coerceBoolean`.
+
+- `debug.forceCloudFallback` — pretend LAN discovery fails for every device, so
+  the whole platform runs over the Tuya Cloud fallback. Lets the cloud path be
+  exercised end-to-end without taking devices off the LAN (needs a configured
+  `cloud` block to be useful).
+- `debug.logCloudHttp` — trace every Tuya Cloud HTTP request/response (method,
+  path, headers, body, status, response) at `debug`, with all credentials
+  (token, signature, password, access key/id, uid) redacted. Verbose and
+  per-request — keep it off in normal operation, and remember Homebridge
+  debug logging must be on to see it.
+
+## Git & PR workflow
+
+- Develop on the branch you've been assigned; never push to `main` directly.
+- `main` is protected and merges via squash; each commit there is auto-published
+  to npm under the `dev` tag, so keep `main` releasable.
+- Match the existing commit style: a concise, imperative subject (the PR number
+  is appended automatically on merge, e.g. `... (#62)`).
+
+</content>
+</invoke>

package/CLAUDE.md

@@ -0,0 +1 @@
+See @AGENTS.md for project guidance.

package/Changelog.md

@@ -4,11 +4,24 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
-* [+] **Tuya Cloud support for devices that can't be reached over the LAN** — most notably battery-powered "sleepy" irrigation/sprinkler timers, which sleep almost all the time and only ever talk to Tuya's cloud, so the local protocol can never reach them. The plugin stays LAN-first: cloud is strictly opt-in. Add a top-level `cloud` credentials block (or a per-device `cloud` object) and set `"cloud": true` on the device.
+* [+] **Tuya Cloud is now a transparent, global fallback for every device.** What started as an experiment to reach battery-powered "sleepy" irrigation timers (which never appear on the LAN) is now a general, optional fallback: add a top-level `cloud` credentials block once and the plugin keeps a single Tuya Cloud/MQTT session alive in the background, falling back to it whenever a device can't be reached on the LAN — a flaky moment, or hardware that's never local. The plugin stays **LAN-first** (local is always tried first and preferred) and cloud remains **strictly opt-in** (nothing runs unless credentials are present).
+  * **No per-device configuration.** There is one global session and no per-device cloud settings. Every device automatically uses the LAN first and the cloud as a fallback; a device with no local `key` is reached over the cloud only. Existing LAN configs (numeric data-points) keep working over the cloud — the data-point id↔code map is learned from Tuya's device shadow (`/v2.0/cloud/thing/{id}/shadow/properties`) — and if both transports fail, HomeKit shows "No Response" as before. This mirrors the official Tuya/Smart Life app (LAN when possible, cloud as a backup).
   * Realtime updates arrive over Tuya's **MQTT** message service (via the optional `mqtt` dependency, installed automatically); initial state and control use the Tuya OpenAPI. There is no polling.
   * Works with both **Custom** and **Smart Home** Cloud projects (the latter via app-account login).
-  * The existing **IrrigationSystem** accessory works unchanged over the cloud — its data-points are simply addressed by Tuya "code" (e.g. `switch_1`, `battery_percentage`) instead of a numeric id; the device logs its codes on startup. Battery-only controllers with no rain sensor: set `"noRainSensor": true`.
-  * See the wiki: **[Tuya Cloud Setup](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)**.
+  * The **IrrigationSystem** accessory no longer has any cloud-specific handling — like every other accessory it's transport-agnostic, with the LAN+cloud fallback handled underneath.
+  * If your devices sometimes drop off the LAN and show "No Response", adding cloud credentials is an easy way to smooth that over. See the wiki: **[Tuya Cloud Setup](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)**.
+* [*] **Fix realtime (MQTT) cloud updates being silently dropped** — external changes (physical buttons, the Tuya app, the device's own timers) now show up in HomeKit within a second or two. The decryptor was verifying the AES-GCM auth tag (`decipher.final()`), but Tuya's real status frames don't carry a tag that verifies against the documented AAD, so every realtime message was being thrown away. Now decrypts with `update()` only, matching the official `tuya/tuya-homebridge` and `0x5e/homebridge-tuya-platform` implementations.
+* [*] **Fix cloud irrigation valves that could be turned on but not off** — the per-zone write coalescer was dropping any command that matched the last-known `device.state`. Cloud devices never optimistically advance `state` (it only moves once the realtime stream confirms the device), so an "off" issued before the "on" was echoed matched the stale "off" and was discarded — HomeKit showed the zone closed while it kept running. Queued commands are now sent as-is (callers already queue only genuine changes).
+* [*] **IrrigationSystem: remove the rain sensor.** It never reported reliably on these devices, and bundling a sensor (a different HomeKit category) in the same accessory forced the Home app to fragment the sprinkler into "sub-accessories" — blocking control from the main tile and hiding the system master on/off. The accessory is now a single, clean sprinkler tile (IrrigationSystem + valves + optional battery); any leftover Contact/Leak sensor service from a previous build is removed automatically on restart. The `noRainSensor`, `rainSensorType`, `rainInverted`, `dpRain` and `rainOnValue` options are gone.
+* [*] **IrrigationSystem: add the HAP Service Label service for multi-valve controllers** — an accessory that exposes a collection of same-type services (more than one `Valve`) must include a `ServiceLabel` service to anchor each valve's `ServiceLabelIndex`. It was missing, so stricter Home app clients (notably iOS) scattered the zones as separate tiles instead of nesting them under the single irrigation tile. The service is added automatically (with the Arabic-numerals namespace) whenever there is more than one valve; user-set zone names still take precedence.
+* [*] **IrrigationSystem: stop the valve toggle flickering after a press** — tapping a zone briefly snapped back to the old state before settling on the new one. The `Active` getters returned the raw `device.state`, which (for cloud devices) only advances once the realtime stream echoes the write back, so a read in that window reported the pre-press value. The getters now report the value HomeKit already shows (optimistic on press, then confirmed/corrected by device-side change events); they still surface "No Response" while disconnected.
+* [*] **Tuya Cloud: report real device online/offline status.** Cloud devices previously always showed as reachable. They now mirror Tuya's `online` flag (read from the device record on connect and re-checked when the realtime stream reconnects), so HomeKit shows **"No Response"** when the device is genuinely offline. If the lookup isn't permitted (the project lacks the device-management API), the device is assumed reachable so control is never blocked.
+* [*] **Signal unreachable devices with `HapStatusError`.** The shared getters (`getStateAsync` / `getDividedStateAsync`, used by nearly every accessory's read handlers, plus the irrigation `Active` getter) threw a plain `Error` to make HomeKit show "No Response". Newer Homebridge logs a characteristic warning for that before falling back to a generic status; they now throw `HapStatusError(SERVICE_COMMUNICATION_FAILURE)` directly — same "No Response", no warning spam. No behaviour change for users.
+* [*] **Surface write and connection failures to HomeKit, universally across device types.** Previously a command sent to an unreachable device was silently dropped while HomeKit still reported the tap as successful, and several accessories kept showing their last-known state instead of going "No Response" — the clearest example was a LAN gate that logged `skipping write, device not connected` yet still appeared online and "accepted" open/close taps. Now:
+  * **Writes** to a disconnected device (or a write the device/cloud rejects) fail the HomeKit operation instead of pretending success. The shared write helpers (`setState` / `setMultiState` / `setMultiStateLegacy` and their `*Async` variants) now signal a communication failure, so accessories whose set handlers swallowed it (garage door, switches/outlets, RGB hue + saturation, blinds, vertical-tilt blinds) report it on a tap.
+  * **Reads** that returned a cached/optimistic or constant value (brightness, colour, hue/saturation, blind position/state, garage-door state, valve in-use/duration, heater state, …) now report **"No Response"** when the device is unreachable — matching the read handlers that already did.
+  * **Cloud** commands that fail over HTTP (a network error, or a command Tuya rejects) are surfaced too: `TuyaCloudDevice.update()` now resolves to the real command result so the write helper can await it, rather than firing and forgetting.
+  * Internal/background writes (auto-shutoff timers, multi-step open/close sequences, debounced batches) stay non-fatal via dedicated non-throwing helpers (`setStateInBackground` / `setMultiStateInBackground` / `setMultiStateLegacyInBackground`), so an unreachable device can never crash Homebridge with an unhandled error.
 
 ## 2.0.1 (2021-03-25)
 This update includes the following changes: