matterbridge-lg-thinq-plugin 0.1.0

package/src/tests/platform/thinq/thinqWasherStopCommandResolver.test.ts

@@ -0,0 +1,392 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+	extractWasherStopCommand,
+	type WasherStopCommandPayload,
+} from '../../../platform/thinq/thinqWasherStopCommandResolver.js';
+
+describe('thinqWasherStopCommandResolver', () => {
+	describe('extractWasherStopCommand', () => {
+		it('should extract WMStop command when present', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						command: 'Set',
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeDefined();
+			expect(result?.command).toBe('Set');
+			expect(result?.dataKey).toBe('washerDryer.state');
+			expect(result?.dataValue).toBe('STOP');
+		});
+
+		it('should fall back to WMOff when WMStop is absent', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMOff: {
+						command: 'Set',
+						dataKey: 'washerDryer.state',
+						dataValue: 'OFF',
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeDefined();
+			expect(result?.dataValue).toBe('OFF');
+		});
+
+		it('should prefer WMStop over WMOff when both present', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						command: 'Set',
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+					},
+					WMOff: {
+						command: 'Set',
+						dataKey: 'washerDryer.state',
+						dataValue: 'OFF',
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.dataValue).toBe('STOP');
+		});
+
+		it('should return undefined when both WMStop and WMOff are absent', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					OtherCommand: {
+						dataKey: 'some.state',
+						dataValue: 'VALUE',
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeUndefined();
+		});
+
+		it('should return undefined when ControlWifi is absent', () => {
+			// Arrange
+			const deviceModel = {
+				OtherProperty: {
+					WMStop: {
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeUndefined();
+		});
+
+		it('should return undefined for empty deviceModel', () => {
+			// Arrange
+			const deviceModel = {};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeUndefined();
+		});
+
+		it('should return undefined when deviceModel is not an object', () => {
+			// Arrange
+			const deviceModel: any = null;
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeUndefined();
+		});
+
+		it('should handle WMStop as non-object gracefully', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: 'string-value',
+					WMOff: {
+						dataKey: 'washerDryer.state',
+						dataValue: 'OFF',
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeDefined();
+			expect(result?.dataValue).toBe('OFF');
+		});
+
+		it('should include optional command field when present', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						command: 'Operation',
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.command).toBe('Operation');
+		});
+
+		it('should omit command field when absent', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.command).toBeUndefined();
+		});
+
+		it('should handle dataSetList when present', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+						dataSetList: {
+							course: 'value1',
+							spin: 'value2',
+						},
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.dataSetList).toBeDefined();
+			expect(result?.dataSetList?.course).toBe('value1');
+			expect(result?.dataSetList?.spin).toBe('value2');
+		});
+
+		it('should fallback to data field when dataSetList is absent', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+						data: {
+							course: 'value1',
+						},
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.dataSetList).toBeDefined();
+			expect(result?.dataSetList?.course).toBe('value1');
+		});
+
+		it('should prefer dataSetList over data field', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+						dataSetList: {
+							course: 'from-dataSetList',
+						},
+						data: {
+							course: 'from-data',
+						},
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.dataSetList?.course).toBe('from-dataSetList');
+		});
+
+		it('should handle dataValue as any type (not just string)', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						dataKey: 'washerDryer.state',
+						dataValue: 123,
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.dataValue).toBe(123);
+		});
+
+		it('should handle boolean dataValue', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						dataKey: 'washerDryer.state',
+						dataValue: true,
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.dataValue).toBe(true);
+		});
+
+		it('should handle null dataValue', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						dataKey: 'washerDryer.state',
+						dataValue: null,
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.dataValue).toBeNull();
+		});
+
+		it('should omit dataSetList when neither dataSetList nor data are objects', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+						dataSetList: 'not-an-object',
+						data: 'also-not-an-object',
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result?.dataSetList).toBeUndefined();
+		});
+
+		it('should handle ControlWifi as non-object gracefully', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: 'not-an-object',
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeUndefined();
+		});
+
+		it('should handle deeply nested undefined properties gracefully', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						dataKey: undefined,
+						dataValue: undefined,
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeDefined();
+			expect(result?.dataKey).toBeUndefined();
+			expect(result?.dataValue).toBeUndefined();
+		});
+
+		it('should include all fields from WMStop in payload', () => {
+			// Arrange
+			const deviceModel = {
+				ControlWifi: {
+					WMStop: {
+						command: 'Operation',
+						dataKey: 'washerDryer.state',
+						dataValue: 'STOP',
+						dataSetList: { course: 'express' },
+					},
+				},
+			};
+
+			// Act
+			const result = extractWasherStopCommand(deviceModel);
+
+			// Assert
+			expect(result).toBeDefined();
+			expect(result?.command).toBe('Operation');
+			expect(result?.dataKey).toBe('washerDryer.state');
+			expect(result?.dataValue).toBe('STOP');
+			expect(result?.dataSetList).toBeDefined();
+		});
+	});
+});

package/src/tests/settings.test.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import { ENGINES, PLUGIN_NAME, PLUGIN_URL, PLUGIN_VERSION } from '../settings.js';
+
+describe('settings', () => {
+	it('should export PLUGIN_NAME matching package.json name', () => {
+		const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+		const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as Record<string, unknown>;
+		expect(PLUGIN_NAME).toBe(pkg.name);
+	});
+
+	it('should export PLUGIN_VERSION matching package.json version', () => {
+		const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+		const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as Record<string, unknown>;
+		expect(PLUGIN_VERSION).toBe(pkg.version);
+	});
+
+	it('should export PLUGIN_URL matching package.json homepage', () => {
+		const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+		const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as Record<string, unknown>;
+		expect(PLUGIN_URL).toBe(pkg.homepage);
+	});
+
+	it('should export ENGINES matching package.json engines', () => {
+		const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+		const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as Record<string, unknown>;
+		expect(ENGINES).toEqual(pkg.engines);
+	});
+});

package/src/utils/mask.ts

@@ -0,0 +1,50 @@
+/** Masks a secret string, leaving only the last `visibleChars` characters visible (e.g. `****abcd`). */
+export function maskSecret(value: string | undefined, visibleChars = 4): string {
+	if (!value) {
+		return '';
+	}
+
+	if (value.length <= visibleChars) {
+		return '*'.repeat(value.length);
+	}
+
+	return '*'.repeat(value.length - visibleChars) + value.slice(-visibleChars);
+}
+
+/** Field names (case-insensitive) whose values are masked by `maskSensitiveFields` before being logged. */
+const SENSITIVE_FIELD_NAMES = new Set([
+	'refresh_token',
+	'refreshtoken',
+	'access_token',
+	'accesstoken',
+	'password',
+	'client_secret',
+	'clientsecret',
+	'secret',
+	'x-emp-token',
+	'authorization',
+]);
+
+/**
+ * Returns a shallow-safe, deep-masked copy of a plain object/record for debug logging: any key matching a known
+ * secret field name (refresh/access token, password, client secret, auth headers) is masked via `maskSecret`;
+ * everything else is copied as-is. Intended for logging outgoing request headers/bodies without leaking secrets.
+ */
+export function maskSensitiveFields(source: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+	if (!source) {
+		return source;
+	}
+
+	const result: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(source)) {
+		if (SENSITIVE_FIELD_NAMES.has(key.toLowerCase())) {
+			result[key] = typeof value === 'string' ? maskSecret(value) : value;
+		} else if (value && typeof value === 'object' && !Array.isArray(value)) {
+			result[key] = maskSensitiveFields(value as Record<string, unknown>);
+		} else {
+			result[key] = value;
+		}
+	}
+
+	return result;
+}

package/tsconfig.base.json

@@ -0,0 +1,25 @@
+{
+	"compilerOptions": {
+		"incremental": true,
+		"composite": true,
+		"target": "esnext",
+		"lib": ["ESNext"],
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"resolveJsonModule": true,
+		"allowJs": true,
+		"checkJs": true,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"preserveConstEnums": true,
+		"allowSyntheticDefaultImports": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"strict": true,
+		"noImplicitAny": true,
+		"alwaysStrict": true,
+		"noImplicitOverride": true,
+		"skipLibCheck": true
+	}
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+	"extends": "./tsconfig.base.json",
+	"compilerOptions": {
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src/**/*.ts"],
+	"exclude": []
+}

package/tsconfig.production.json

@@ -0,0 +1,13 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"incremental": false,
+		"composite": false,
+		"declaration": false,
+		"declarationMap": false,
+		"sourceMap": false,
+		"removeComments": true
+	},
+	"include": ["src/**/*.ts"],
+	"exclude": ["**/*.spec.ts", "**/*.test.ts", "**/__test__/*"]
+}

package/tsconfig.vitest.json

@@ -0,0 +1,5 @@
+{
+	"extends": "./tsconfig.base.json",
+	"include": ["**/*.spec.ts", "**/*.test.ts", "**/tests/**/*.ts"],
+	"exclude": []
+}

package/vite.config.ts

@@ -0,0 +1,43 @@
+// eslint-disable
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+// vite.config.ts
+
+// This Vitest configuration is designed for a TypeScript project.
+
+import { defineConfig } from 'vitest/config';
+import { fileURLToPath } from 'node:url';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+	plugins: [tsconfigPaths()],
+	test: {
+		include: ['src/**/*.test.ts', 'src/**/*.spec.ts'],
+		exclude: ['dist', 'node_modules', 'src/pluginTemplate/**', 'src/cli/**', 'src/cli.ts'],
+		globals: true,
+		clearMocks: true,
+		restoreMocks: true,
+		environment: 'node',
+		maxWorkers: 100,
+		coverage: {
+			provider: 'v8', // default, but explicit
+			reporter: ['text', 'lcov'],
+			include: ['src/**/*.{ts,tsx,js,jsx}'],
+			exclude: [
+				// Exclude test files that may live under src
+				'src/**/*.test.{ts,tsx,js,jsx}',
+				'src/**/*.spec.{ts,tsx,js,jsx}',
+				// Exclude helper file(s) not meant for coverage
+				'src/tests/**/*.ts',
+				// Exclude type declaration files
+				'src/**/*.d.ts',
+			],
+			thresholds: {
+				statements: 75,
+				branches: 75,
+				functions: 75,
+				lines: 75,
+			},
+		},
+	},
+});

package/wiki/memory-archive.md

@@ -0,0 +1,12 @@
+# Memory Archive
+
+Older entries pruned from `.claude/memory.md` to respect its per-section cap. Consult when working on the areas named below.
+
+## Common Pitfalls (archived)
+
+- `classifyIslands` (`legacyIslandDetection.ts`) size-heuristic bug (Jul 27, fixed): was gating per `hasNoWallOrZoneData` map-wide; now evaluates per-island as last-resort fallback — deleted 4-line variable, removed gate from condition, updated doc comment.
+- Implementer must NOT run full builds or the whole test suite — its gate is `format:ci` → `lint:fix:ci` → `type-check:ci` only; `build:local:ci`/`test:ci` belong to compiler/test-writer.
+- `platformRunner.ts:120` writes `activeMapId` BEFORE `handleActiveMapChanged` — a guard inside the handler can't prevent `activeMapId` desync, and the same-map guard (`:119`) then swallows an identical-mapId retry.
+- `SELECT_AREAS` empty-input path (`roborockVacuumCleaner.ts:164-176`) must NOT call `trySwitchMap` — keep empty vs explicit branches structurally separate with early `return`, else V10/V1 (`activeMapId=-1`) fires unguarded `switchMap` on every global-clean.
+- ESLint `preserve-caught-error` requires re-thrown errors to carry `{ cause: err }` — omitting it fails `lint:fix:ci` even when the message embeds the original error text.
+- ESLint `no-base-to-string` prohibits stringifying `err.cause` directly in templates (`String(err.cause)`) — check `if (cause instanceof Error)` first, then safely access `.message`; this prevents accidental `[object Object]` in logs.

package/wiki/reference-workspaces.md

@@ -0,0 +1,23 @@
+# Reference Workspaces (allowlist)
+
+External codebases agents may consult, **read-only**. Investigator and technical-architect may ONLY read paths listed here — anything not listed is out of bounds.
+
+**Priority = list order.** Agents consult top-first and stop early once the question is answered.
+
+Added for the `migrate-lg-thinq-to-matterbridge` task (Sep 8, 2026).
+
+| Name                                  | Path                                                                         | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| matterbridge-example-dynamic-platform | `/Volumes/ExternalSSD/code/references/matterbridge-example-dynamic-platform` | Canonical Matterbridge dynamic-platform plugin shape: lifecycle hooks, device factories (`matterbridge/devices`), config schema, build tooling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| homebridge-lg-thinq                   | `/Volumes/ExternalSSD/code/references/homebridge-lg-thinq`                   | Source logic to port: LG ThinQ cloud OAuth/auth flow, API client, device discovery, device type classes, capability mapping, MQTT/polling event model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ioBroker.lg-thinq                     | `/Volumes/ExternalSSD/code/references/ioBroker.lg-thinq`                     | Second, independent LG ThinQ cloud implementation (JS, by TA2k, v1.2.2): per-device-type modules in `lib/` (e.g. `air_conditioning.js`, `heat_pump.js`), model JSON capability tables in `lib/modelJsonUri`, `main.js` auth/poll/MQTT flow. Use to cross-check payloads/scales/field names against homebridge-lg-thinq.                                                                                                                                                                                                                                                                                                                                                                           |
+| rethink                               | `/Volumes/ExternalSSD/code/references/rethink`                               | anszom/rethink (GPL-2.0, TypeScript): a LOCAL replacement for the LG ThinQ cloud that talks to appliances over LG's local wire protocol (TLV over a local MQTT broker) and exposes them to Home Assistant. READ ONLY for ideas, never copy code (license). Best for how the AC itself behaves: `cloud/devices/RAC_056905_WW.ts` is the user's exact AC model (field-to-feature mapping, ranges, quirks such as the energy sensor bias). `bridge/thinqApi.ts`, `oauth2.ts`, `thinq2connection.ts`, `tools/lgcloud-monitor.ts` show how the real cloud is reached. It does NOT use the official control API, so it cannot explain cloud error codes or `airState.*` names; match fields by meaning. |
+| homebridge-webos-tv                   | `/Volumes/ExternalSSD/code/references/homebridge-webos-tv`                   | SECOND source to port: LG webOS TV control over local network/websocket (SSAP protocol), NOT the ThinQ cloud API — distinct auth/connection model (local client-key pairing).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| matterbridge-roborock-vacuum-plugin   | `/Volumes/ExternalSSD/code/matterbridge-roborock-vacuum-plugin`              | Sibling plugin, closest structural precedent for a prior Homebridge→Matterbridge migration in this family (folder layout, matterbridge API usage, config/build tooling, node-persist token storage).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+
+## Rules
+
+- Read-only — never modify, format, or stage files in these paths.
+- CodeGraph does NOT work here (it indexes this repo only) — use Grep/Glob/Read.
+- Cite findings as `<workspace-name>/path/to/file:line` in answers.
+- To add a workspace: append a row here (with a one-line note on what it is good for) — no other change needed.