homebridge-tuya-plus 3.14.0-dev.33 → 3.14.0-dev.34

package/AGENTS.md

@@ -131,6 +131,20 @@ devices already paired in HomeKit; a careless change can break them silently.
   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).
+
 ## Git & PR workflow
 
 - Develop on the branch you've been assigned; never push to `main` directly.

package/index.js

@@ -79,6 +79,20 @@ let Characteristic,
   AdaptiveLightingController,
   UUID;
 
+// Lenient boolean coercion for platform-level config flags, mirroring
+// BaseAccessory._coerceBoolean so the same true / 'true' / 1 spellings users
+// already use on device options are accepted on top-level options too.
+function coerceBoolean(value, defaultValue) {
+  const df = defaultValue || false;
+  return typeof value === 'boolean'
+    ? value
+    : typeof value === 'string'
+      ? value.toLowerCase().trim() === 'true'
+      : typeof value === 'number'
+        ? value !== 0
+        : df;
+}
+
 module.exports = function (homebridge) {
   ({
     platformAccessory: PlatformAccessory,
@@ -221,6 +235,37 @@ class TuyaLan {
       return; // cloud-only (or empty) configuration: nothing to discover over the LAN
     }
 
+    // Debug switch: pretend LAN discovery fails for every device so the whole
+    // platform runs over the Tuya Cloud fallback — a way to exercise the cloud
+    // path end-to-end without taking devices off the LAN. We simply never start
+    // discovery (and never attach a LAN backend), leaving the cloud session each
+    // device was already wired with as its only transport. Useless without a
+    // configured cloud session — the affected devices then have no transport at
+    // all, so say so per device rather than failing silently.
+    if (coerceBoolean(this._debugConfig().forceCloudFallback)) {
+      this.log.warn(
+        'debug.forceCloudFallback is set: skipping LAN discovery; every device is forced onto the Tuya Cloud fallback.',
+      );
+      lanDeviceIds.forEach((deviceId) => {
+        const tuyaDevice = this.tuyaDevices.get(deviceId);
+        if (!tuyaDevice) return;
+        if (tuyaDevice.cloud) {
+          this.log.info(
+            'Forcing %s (%s) onto the Tuya Cloud fallback (debug.forceCloudFallback).',
+            tuyaDevice.context.name,
+            deviceId,
+          );
+        } else {
+          this.log.error(
+            'debug.forceCloudFallback is set but %s (%s) has no Tuya Cloud session, so it can\'t be reached.',
+            tuyaDevice.context.name,
+            deviceId,
+          );
+        }
+      });
+      return;
+    }
+
     this.log.info('Starting discovery...');
 
     TuyaDiscovery.start({ ids: lanDeviceIds, log: this.log }).on(
@@ -279,6 +324,17 @@ class TuyaLan {
     }, this.config.discoverTimeout ?? DEFAULT_DISCOVER_TIMEOUT);
   }
 
+  // The undocumented top-level `debug` block holds switches that only matter
+  // when developing or testing the plugin (e.g. forcing the Tuya Cloud path).
+  // It is intentionally absent from config.schema.json so it never surfaces in
+  // the Homebridge UI. Always returns an object so callers can read a flag
+  // without first guarding for the block's presence.
+  _debugConfig() {
+    return this.config.debug && typeof this.config.debug === 'object'
+      ? this.config.debug
+      : {};
+  }
+
   // A device showed up on the LAN that isn't in the user's config. When the
   // optional cloud session is available we look the device up there first, so
   // the warning can name it (and hint at its product/category) and the user

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.33",
+  "version": "3.14.0-dev.34",
   "description": "A community-maintained Homebridge plugin for controlling Tuya devices in HomeKit. LAN-first, with an optional Tuya Cloud fallback for any device the LAN can't reach.",
   "main": "index.js",
   "scripts": {

package/test/index.test.js

@@ -136,6 +136,36 @@ describe('TuyaLan — discovery routing', () => {
     });
 });
 
+describe('TuyaLan — debug.forceCloudFallback', () => {
+    test('skips LAN discovery so a keyed device never attaches a LAN backend', () => {
+        run({cloud: CLOUD, debug: {forceCloudFallback: true}, devices: [SW()]});
+        expect(TuyaDiscovery.start).not.toHaveBeenCalled();
+        expect(TuyaDiscovery.on).not.toHaveBeenCalled();
+        expect(instanceFor('bf11111111111111').attachLan).not.toHaveBeenCalled();
+    });
+
+    test('the forced device keeps its shared cloud session as its only transport', () => {
+        run({cloud: CLOUD, debug: {forceCloudFallback: true}, devices: [SW()]});
+        expect(propsFor('bf11111111111111').cloudApi).toBeDefined();
+    });
+
+    test('off (or absent) leaves discovery running as usual', () => {
+        run({cloud: CLOUD, debug: {forceCloudFallback: false}, devices: [SW()]});
+        expect(TuyaDiscovery.start).toHaveBeenCalledTimes(1);
+    });
+
+    test('lenient boolean spellings are accepted', () => {
+        run({cloud: CLOUD, debug: {forceCloudFallback: 'true'}, devices: [SW()]});
+        expect(TuyaDiscovery.start).not.toHaveBeenCalled();
+    });
+
+    test('without a cloud session, the unreachable device is reported as an error', () => {
+        const platform = run({debug: {forceCloudFallback: true}, devices: [SW()]});
+        expect(TuyaDiscovery.start).not.toHaveBeenCalled();
+        expect(platform.log.error).toHaveBeenCalled();
+    });
+});
+
 describe('TuyaLan — unconfigured device discovery', () => {
     const UNKNOWN = {id: 'bf99999999999999', ip: '10.0.0.9'};
     const BARE = 'Discovered a device that has not been configured yet (%s@%s).';