homebridge-tuya-plus 3.14.0-beta.2 → 3.14.0-dev.10

package/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Changes to CI/release automation require the maintainer's review.
+# Enforced only when branch protection on `main` has
+# "Require review from Code Owners" enabled.
+/.github/workflows/ @adrianjagielak
+/.github/CODEOWNERS  @adrianjagielak

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

@@ -0,0 +1,413 @@
+name: Publish to npm (dev + PR test builds)
+
+# 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`.
+#
+# 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.
+#
+# 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.
+#
+# 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 -> `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; jobs opt into more only where needed.
+permissions:
+  contents: read
+
+# 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: ${{ 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
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run test
+
+  # Unprivileged: decides whether this push should publish a dev build, and
+  # 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 }}
+      version: ${{ steps.ver.outputs.version }}
+    steps:
+      # Full history so we can read package.json from before this push.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Skip dev builds for release commits: if package.json's version
+      # changed anywhere in this push (before -> after), treat it as a manual
+      # release and publish nothing. If we can't determine the previous
+      # version (first push, manual dispatch, missing file), default to
+      # publishing — a dev build is the safe fallback.
+      - name: Decide whether to publish a dev build
+        id: check
+        run: |
+          CURR="$(node -p "require('./package.json').version")"
+          BEFORE="${{ github.event.before }}"
+          if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
+            BEFORE="$(git rev-parse --verify --quiet HEAD~1 || true)"
+          fi
+          PREV=""
+          if [ -n "$BEFORE" ] && git cat-file -e "$BEFORE:package.json" 2>/dev/null; then
+            git show "$BEFORE:package.json" > "$RUNNER_TEMP/prev-package.json"
+            PREV="$(node -p "require('$RUNNER_TEMP/prev-package.json').version")"
+          fi
+          echo "Previous version: ${PREV:-<unknown>}"
+          echo "Current version:  $CURR"
+          if [ -n "$PREV" ] && [ "$PREV" != "$CURR" ]; then
+            echo "::notice::package.json version changed ($PREV -> $CURR); skipping dev publish (treated as a manual release commit)."
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Dev builds target the next MINOR release (minor +1, patch -> 0).
+      - name: Compute dev version
+        id: ver
+        run: |
+          NEXT="$(node -e "const v=require('./package.json').version.split('.'); v[1]=Number(v[1])+1; v[2]=0; console.log(v.join('.'))")"
+          VERSION="${NEXT}-dev.${GITHUB_RUN_NUMBER}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Will publish $VERSION"
+
+  publish:
+    needs: [test, prepare]
+    # 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.
+    environment: npm-dev
+    permissions:
+      contents: read # checkout
+      id-token: write # OIDC -> npm Trusted Publishing (no stored token)
+    steps:
+      - uses: actions/checkout@v4
+
+      - 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
+
+      # Writes package.json on the runner only; nothing is committed.
+      - name: Set version
+        run: npm version "${{ needs.prepare.outputs.version }}" --no-git-tag-version --allow-same-version --ignore-scripts
+
+      # No NODE_AUTH_TOKEN: npm exchanges the OIDC id-token for a
+      # short-lived, package-scoped credential at publish time.
+      # --ignore-scripts ensures no lifecycle script runs with that credential.
+      # --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,120 @@
+# 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.
+
+## 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.
+
+## 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

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file. This project uses [semantic versioning](https://semver.org/).
 
+## 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.
+  * 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)**.
+
 ## 2.0.1 (2021-03-25)
 This update includes the following changes:
 

package/Readme.MD

@@ -69,6 +69,14 @@ Protocol **3.5** is currently the newest Tuya LAN protocol in existence: it is t
 
 This plugin is nevertheless **3.6-ready**: if a device reports a newer protocol version (e.g. `3.6`) in its broadcast, the plugin automatically talks to it using the newest (3.5/GCM) protocol stack while tagging payloads with the device's reported version — the same forward-compatibility strategy used by tinytuya. Should such a device misbehave, you can pin it to a specific protocol with the `forceVersion` device option (e.g. `"forceVersion": "3.5"`), or use `version` to set a protocol for devices that can't be discovered (e.g. on another subnet).
 
+## Cloud devices (for hardware that can't be controlled locally)
+
+This is a **LAN-first** plugin — virtually every Tuya device is controlled locally, which is faster, more private, and keeps working without internet. A few devices, though, simply **can't** be reached over the LAN: battery-powered "sleepy" devices — for example the **irrigation / faucet timers** — sleep almost all the time and only ever connect out to Tuya's cloud, so they never answer on the local network.
+
+For exactly these cases the plugin can talk to a device through the **Tuya Cloud** instead — strictly **opt-in, per device**. You add your Tuya Cloud project credentials once and set `"cloud": true` on the device; everything else works the same.
+
+👉 **[Tuya Cloud Setup guide](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)** — how to get credentials and configure a cloud device.
+
 ## Installation Instructions
 
 #### Option 1: Install via Homebridge Config UI X:
@@ -81,6 +89,33 @@ Search for "Tuya" in [homebridge-config-ui-x](https://github.com/oznu/homebridge
 sudo npm install -g homebridge-tuya-plus
 ```
 
+#### Bleeding-edge (`dev`) builds:
+
+Every commit to `main` is automatically published to npm under the `dev` tag — a
+separate, unstable channel. The stable release always stays on `latest`, so this
+won't affect normal installs. To try the latest in-development build:
+
+```
+sudo npm install -g homebridge-tuya-plus@dev
+```
+
+These are versioned like `3.14.0-dev.<n>` and may be unstable; use the default
+install above for production.
+
+#### Testing a specific pull request:
+
+Maintainers can publish an unmerged PR as a throwaway test build by commenting
+`/publish` on it. The build goes to its own `pr-<number>` tag — never `latest`
+or `dev` — so it never reaches normal installs. The bot replies on the PR with
+the exact install command, e.g.:
+
+```
+sudo npm install -g homebridge-tuya-plus@pr-57
+```
+
+Each build also gets a unique, immutable version like `3.14.0-pr.57.<n>` that you
+can pin or paste into the Homebridge UI's "Install Alternate Version" field.
+
 ## Configuration
 > UI