homebridge-plugin-klares4 2.0.1-beta1 → 2.0.1

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-03-13
+
+### Added
+
+- KSA import pipeline (`ksaImport`) with deterministic derivation for thermostat command routing, Domus sensor mapping, room mapping, and optional custom names.
+- Sanitized KSA runtime cache (`klares4-ksa-cache.json`) with whitelist-only structural metadata (no raw backup persistence).
+- Bilingual technical documentation under `docs/en` and `docs/it` covering architecture, websocket behavior, Domus routing, config, and troubleshooting.
+- CI/CD upgrade:
+  - Node 20/22 CI validation matrix with strict type-check + tests + build artifact
+  - npm publish workflow via GitHub Actions (tag/manual release path, provenance, and publish guards).
+
+### Fixed
+
+- Thermostat authoritative state alignment on Domus installations using `STATUS_TEMPERATURES` for realtime mode/setpoint/current state.
+- Thermostat routing mismatch on systems where output IDs, Domus sensor IDs, and `CFG_THERMOSTATS.ID` are not numerically aligned.
+- Startup synchronization robustness by preloading thermostat structural mapping from sanitized KSA cache when `PRG_THERMOSTATS` is not exposed by firmware.
+- Degraded routing behavior now evaluates mapped Domus sensor candidates before raw output fallback in non-PRG environments.
+
+## [2.0.1-beta2] - 2026-03-13
+
+### Added
+
+- New KSA import workflow in plugin config (`ksaImport`) to parse central backup metadata and derive deterministic routing data.
+- Sanitized KSA cache persisted in Homebridge storage (`klares4-ksa-cache.json`) with thermostat/output/sensor/room mappings only (no raw backup persistence).
+- Automatic derivation from KSA for:
+  - `domusThermostat.manualCommandPairs` (`output -> CFG/STATUS thermostat ID`)
+  - `domusThermostat.manualPairs` (`output -> Domus sensor`)
+  - optional `roomMapping` and optional `customNames`.
+
+### Fixed
+
+- Runtime thermostat routing now preloads program mappings from KSA cache when realtime `PRG_THERMOSTATS` is unavailable on panel firmware.
+- Degraded command resolver now evaluates mapped Domus sensor IDs before raw output fallback, improving compatibility in non-PRG environments.
+- Initial websocket state can bootstrap thermostat program maps from cached KSA data to avoid startup desynchronization.
+
 ## [2.0.1-beta1] - 2026-03-13
 
 ### Fixed

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Paolo Trivi
+Copyright (c) 2025-26 Paolo Trivisonno
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE. 
+SOFTWARE. 

package/README.md

@@ -8,6 +8,13 @@ Complete plugin for Ksenia Lares4 systems integrating security zones, lights, co
 
 ---
 
+## Full Documentation
+
+- English docs: `docs/en/`
+- Documentazione italiana: `docs/it/`
+
+---
+
 ## English Documentation
 
 ### Features
@@ -109,6 +116,7 @@ The plugin can be fully configured via the Homebridge UI graphical interface. Re
 | `allowInsecureTls`  | boolean  | false        | Disable TLS certificate validation (trusted LAN only) |
 | `logLevel`          | number   | 1            | 0=minimal, 1=normal, 2=debug    |
 | `domusThermostat`   | object   | enabled/freshness defaults | DOMUS thermostat mapping, manual overrides, freshness fallback |
+| `ksaImport`         | object   | disabled     | Import KSA backup metadata for thermostat routing, room mapping and optional config apply |
 | `debug`             | boolean  | false        | Detailed logging                |
 | `excludeZones`      | string[] | []           | Zones to exclude                |
 | `excludeOutputs`    | string[] | []           | Outputs to exclude              |
@@ -251,11 +259,31 @@ npm run verify
 
 This runs:
 
-- max file size gate (`src/**/*.ts` <= 300 lines),
+- max file size gate (`src/**/*.ts` <= 350 lines),
 - strict TypeScript checks (`--noUnusedLocals --noUnusedParameters`),
 - full test suite,
 - build compatibility gate.
 
+### CI/CD
+
+GitHub Actions workflows:
+
+- `CI` (`.github/workflows/ci.yml`): Node 20/22 validation, strict type-checks, tests, build artifact.
+- `Release Publish` (`.github/workflows/release-publish.yml`): npm publish with provenance from tags (`v*`) or manual dispatch.
+
+Trusted publishing:
+
+- `Release Publish` uses GitHub OIDC trusted publishing (`id-token: write`).
+- No `NPM_TOKEN` secret is required.
+
+Release policy:
+
+- tag push `v<package.json version>` triggers publish;
+- npm dist-tag auto-derived from version:
+  - `*-beta*` -> `beta`
+  - `*-rc*` -> `rc`
+  - stable -> `latest`
+
 ### Roadmap
 
 #### Planned for v1.2.0
@@ -401,6 +429,7 @@ Il plugin puo essere configurato completamente tramite l'interfaccia grafica di
 | `heartbeatInterval` | number   | 30000        | Intervallo heartbeat (ms)       |
 | `logLevel`          | number   | 1            | 0=minimal, 1=normal, 2=debug    |
 | `domusThermostat`   | object   | default attivi | Mapping termostati DOMUS, override manuali e fallback freshness |
+| `ksaImport`         | object   | disabilitato | Import metadata da backup KSA per routing termostati, room mapping e apply opzionale |
 | `debug`             | boolean  | false        | Logging dettagliato             |
 | `excludeZones`      | string[] | []           | Zone da escludere               |
 | `excludeOutputs`    | string[] | []           | Output da escludere             |

package/config.schema.json

@@ -4,7 +4,7 @@
     "singular": true,
     "customUi": false,
     "headerDisplay": "<div style='margin-bottom:12px;'><h3 style='margin:0 0 6px 0;'>Klares4 - Ksenia Lares4 per Homebridge</h3><p style='margin:0 0 12px 0;'>Plugin Homebridge per controllo locale della centrale Ksenia Lares4.</p><div style='padding:10px 12px;border:1px solid currentColor;border-radius:8px;'><strong>Prerequisiti:</strong><ul style='margin:8px 0 0 18px;padding:0;'><li>Centrale raggiungibile in rete locale</li><li>Interfaccia WebSocket abilitata</li><li>PIN utente valido (4-8 cifre)</li></ul></div></div>",
-    "footerDisplay": "<div style='margin-top:16px;padding-top:12px;border-top:1px solid currentColor;'><p style='margin:0 0 8px 0;'>Versione 2.0.1-beta1 • Sviluppato da Paolo Trivisonno</p><p style='margin:0;'><a href='https://github.com/paolo-trivi/homebridge-plugin-klares4' target='_blank' rel='noopener noreferrer'>Documentazione</a> | <a href='https://github.com/paolo-trivi/homebridge-plugin-klares4/issues' target='_blank' rel='noopener noreferrer'>Segnala Bug</a> | <a href='https://github.com/sponsors/paolo-trivi' target='_blank' rel='noopener noreferrer'>Supporta</a></p></div>",
+    "footerDisplay": "<div style='margin-top:16px;padding-top:12px;border-top:1px solid currentColor;'><p style='margin:0 0 8px 0;'>Versione 2.0.1 • Sviluppato da Paolo Trivisonno</p><p style='margin:0;'><a href='https://github.com/paolo-trivi/homebridge-plugin-klares4' target='_blank' rel='noopener noreferrer'>Documentazione</a> | <a href='https://github.com/paolo-trivi/homebridge-plugin-klares4/issues' target='_blank' rel='noopener noreferrer'>Segnala Bug</a> | <a href='https://github.com/sponsors/paolo-trivi' target='_blank' rel='noopener noreferrer'>Supporta</a></p></div>",
     "schema": {
         "type": "object",
         "properties": {
@@ -300,6 +300,58 @@
                     }
                 }
             },
+            "ksaImport": {
+                "type": "object",
+                "default": {
+                    "enabled": false,
+                    "applyAtStartup": false,
+                    "applyDomusMappings": true,
+                    "applyRoomMapping": true,
+                    "applyCustomNames": false,
+                    "applyExclusionSuggestions": false
+                },
+                "properties": {
+                    "enabled": {
+                        "title": "Abilita Import KSA",
+                        "type": "boolean",
+                        "default": false,
+                        "description": "Carica il file backup .ksa per generare mapping e metadata strutturali"
+                    },
+                    "filePath": {
+                        "title": "Percorso File .ksa",
+                        "type": "string",
+                        "placeholder": "/var/lib/homebridge/prg-xxxx.ksa",
+                        "description": "Percorso assoluto del file backup .ksa esportato dalla centrale"
+                    },
+                    "applyAtStartup": {
+                        "title": "Applica su config al riavvio",
+                        "type": "boolean",
+                        "default": false,
+                        "description": "Preview + apply: se attivo, applica su config.json e poi si resetta a false"
+                    },
+                    "applyDomusMappings": {
+                        "title": "Applica mapping Domus termostati",
+                        "type": "boolean",
+                        "default": true
+                    },
+                    "applyRoomMapping": {
+                        "title": "Applica room mapping",
+                        "type": "boolean",
+                        "default": true
+                    },
+                    "applyCustomNames": {
+                        "title": "Applica nomi personalizzati",
+                        "type": "boolean",
+                        "default": false
+                    },
+                    "applyExclusionSuggestions": {
+                        "title": "Applica suggerimenti esclusioni",
+                        "type": "boolean",
+                        "default": false,
+                        "description": "Non consigliato di default: applica liste esclusione suggerite dal parser"
+                    }
+                }
+            },
             "mqtt": {
                 "type": "object",
                 "properties": {
@@ -619,6 +671,61 @@
                         }
                     ]
                 },
+                {
+                    "type": "fieldset",
+                    "title": "Import KSA",
+                    "expandable": false,
+                    "items": [
+                        {
+                            "key": "ksaImport.enabled",
+                            "title": "Import KSA Attivo"
+                        },
+                        {
+                            "key": "ksaImport.filePath",
+                            "title": "Percorso File .ksa",
+                            "condition": {
+                                "functionBody": "return model.ksaImport && model.ksaImport.enabled === true;"
+                            }
+                        },
+                        {
+                            "key": "ksaImport.applyAtStartup",
+                            "title": "Apply alla Config al Prossimo Avvio",
+                            "description": "Esegue preview nei log e applica i blocchi selezionati, poi torna automaticamente OFF",
+                            "condition": {
+                                "functionBody": "return model.ksaImport && model.ksaImport.enabled === true;"
+                            }
+                        },
+                        {
+                            "type": "flex",
+                            "flex-flow": "row wrap",
+                            "condition": {
+                                "functionBody": "return model.ksaImport && model.ksaImport.enabled === true;"
+                            },
+                            "items": [
+                                {
+                                    "key": "ksaImport.applyDomusMappings",
+                                    "title": "Domus Mapping",
+                                    "flex": "1 1 200px"
+                                },
+                                {
+                                    "key": "ksaImport.applyRoomMapping",
+                                    "title": "Room Mapping",
+                                    "flex": "1 1 200px"
+                                },
+                                {
+                                    "key": "ksaImport.applyCustomNames",
+                                    "title": "Custom Names",
+                                    "flex": "1 1 200px"
+                                },
+                                {
+                                    "key": "ksaImport.applyExclusionSuggestions",
+                                    "title": "Exclusions",
+                                    "flex": "1 1 200px"
+                                }
+                            ]
+                        }
+                    ]
+                },
                 {
                     "type": "fieldset",
                     "title": "Scenari",

package/dist/ksa/cache-service.d.ts

@@ -0,0 +1,11 @@
+import type { Logger } from 'homebridge';
+import type { KsaSanitizedCache } from '../types';
+export declare class KsaCacheService {
+    private readonly log;
+    private readonly cachePath;
+    constructor(storagePath: string, log: Logger);
+    get path(): string;
+    save(cache: KsaSanitizedCache): Promise<void>;
+    load(): Promise<KsaSanitizedCache | undefined>;
+}
+//# sourceMappingURL=cache-service.d.ts.map

package/dist/ksa/cache-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-service.d.ts","sourceRoot":"","sources":["../../src/ksa/cache-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAIlD,qBAAa,eAAe;IAGS,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,WAAW,EAAE,MAAM,EAAmB,GAAG,EAAE,MAAM;IAI7D,IAAW,IAAI,IAAI,MAAM,CAExB;IAEY,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,IAAI,IAAI,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;CAmB9D"}

package/dist/ksa/cache-service.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KsaCacheService = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const CACHE_FILE_NAME = 'klares4-ksa-cache.json';
+class KsaCacheService {
+    constructor(storagePath, log) {
+        this.log = log;
+        this.cachePath = path.join(storagePath, CACHE_FILE_NAME);
+    }
+    get path() {
+        return this.cachePath;
+    }
+    async save(cache) {
+        await fs.promises.writeFile(this.cachePath, JSON.stringify(cache, null, 2), 'utf8');
+    }
+    async load() {
+        try {
+            const raw = await fs.promises.readFile(this.cachePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object') {
+                return undefined;
+            }
+            if (!Array.isArray(parsed.thermostatPrograms)) {
+                return undefined;
+            }
+            return parsed;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!message.includes('ENOENT')) {
+                this.log.warn(`Unable to load KSA cache: ${message}`);
+            }
+            return undefined;
+        }
+    }
+}
+exports.KsaCacheService = KsaCacheService;
+//# sourceMappingURL=cache-service.js.map

package/dist/ksa/cache-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-service.js","sourceRoot":"","sources":["../../src/ksa/cache-service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AACzB,2CAA6B;AAI7B,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEjD,MAAa,eAAe;IAGxB,YAAY,WAAmB,EAAmB,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;QACzD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IAC7D,CAAC;IAED,IAAW,IAAI;QACX,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,KAAwB;QACtC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACxF,CAAC;IAEM,KAAK,CAAC,IAAI;QACb,IAAI,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsB,CAAC;YACpD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACxC,OAAO,SAAS,CAAC;YACrB,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,EAAE,CAAC;gBAC5C,OAAO,SAAS,CAAC;YACrB,CAAC;YACD,OAAO,MAAM,CAAC;QAClB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC9B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,6BAA6B,OAAO,EAAE,CAAC,CAAC;YAC1D,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;IACL,CAAC;CACJ;AAlCD,0CAkCC"}

package/dist/ksa/derive.d.ts

@@ -0,0 +1,3 @@
+import type { KsaImportResult, ParsedKsaProgram } from './types';
+export declare function deriveKsaImportResult(program: ParsedKsaProgram, sourceFilePath: string | undefined, rawBytes: Buffer): KsaImportResult;
+//# sourceMappingURL=derive.d.ts.map

package/dist/ksa/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/ksa/derive.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAoB,eAAe,EAAgB,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjG,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,gBAAgB,EACzB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,QAAQ,EAAE,MAAM,GACjB,eAAe,CAgBjB"}

package/dist/ksa/derive.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveKsaImportResult = deriveKsaImportResult;
+const crypto_1 = require("crypto");
+const device_state_projector_1 = require("../websocket/device-state-projector");
+function deriveKsaImportResult(program, sourceFilePath, rawBytes) {
+    const cache = buildSanitizedCache(program, sourceFilePath, rawBytes);
+    const derivedConfig = buildDerivedConfig(program, cache);
+    return {
+        summary: {
+            outputs: program.outputs.length,
+            zones: program.zones.length,
+            scenarios: program.scenarios.length,
+            sensors: program.busHas.length,
+            thermostats: program.thermostats.length,
+            rooms: program.rooms.length,
+            maps: program.maps.length,
+        },
+        cache,
+        derivedConfig,
+    };
+}
+function buildSanitizedCache(program, sourceFilePath, rawBytes) {
+    const thermostatProgramIdByOutputId = {};
+    const domusSensorIdByThermostatProgramId = {};
+    const thermostatPrograms = program.thermostats
+        .map((thermostat) => {
+        const thermostatProgramId = asId(thermostat.ID);
+        if (!thermostatProgramId) {
+            return null;
+        }
+        const heatingOutputId = normalizeNullableId(thermostat.HEATING_OUT);
+        const coolingOutputId = normalizeNullableId(thermostat.COOLING_OUT);
+        const domusSensorId = normalizeNullableId(thermostat.PERIPH?.PID);
+        if (heatingOutputId) {
+            thermostatProgramIdByOutputId[heatingOutputId] = thermostatProgramId;
+        }
+        if (coolingOutputId) {
+            thermostatProgramIdByOutputId[coolingOutputId] = thermostatProgramId;
+        }
+        if (domusSensorId) {
+            domusSensorIdByThermostatProgramId[thermostatProgramId] = domusSensorId;
+        }
+        return {
+            id: thermostatProgramId,
+            description: normalizeLabel(thermostat.DES) ?? undefined,
+            heatingOutputId: heatingOutputId ?? undefined,
+            coolingOutputId: coolingOutputId ?? undefined,
+            domusSensorId: domusSensorId ?? undefined,
+        };
+    })
+        .filter((entry) => entry !== null);
+    return {
+        sourceFilePath,
+        sourceFileHash: (0, crypto_1.createHash)('sha256').update(rawBytes).digest('hex'),
+        parsedAt: new Date().toISOString(),
+        thermostatPrograms,
+        thermostatProgramIdByOutputId,
+        domusSensorIdByThermostatProgramId,
+        outputNamesById: toNameRecord(program.outputs),
+        zoneNamesById: toNameRecord(program.zones),
+        scenarioNamesById: toNameRecord(program.scenarios),
+        domusSensorNamesById: toNameRecord(program.busHas.map((sensor) => ({
+            ID: sensor.ID,
+            DES: sensor.DOMUS?.DES ?? `Sensor ${sensor.ID}`,
+        }))),
+        roomNameById: toNameRecord(program.rooms),
+        roomDeviceRefs: toRoomDeviceRefs(program.maps),
+    };
+}
+function buildDerivedConfig(program, cache) {
+    const outputById = new Map(program.outputs.map((output) => [String(output.ID), output]));
+    const roomNameById = cache.roomNameById;
+    const roomDevices = new Map();
+    for (const map of cache.roomDeviceRefs) {
+        const roomName = roomNameById[map.roomId];
+        if (!roomName) {
+            continue;
+        }
+        const resolvedDeviceIds = resolveRoomMapToDeviceIds(map, outputById);
+        if (resolvedDeviceIds.length === 0) {
+            continue;
+        }
+        const bucket = roomDevices.get(roomName) ?? new Set();
+        for (const deviceId of resolvedDeviceIds) {
+            bucket.add(deviceId);
+        }
+        roomDevices.set(roomName, bucket);
+    }
+    return {
+        domusThermostat: {
+            manualPairs: Object.entries(cache.thermostatProgramIdByOutputId)
+                .map(([outputId, thermostatProgramId]) => ({
+                thermostatOutputId: outputId,
+                domusSensorId: cache.domusSensorIdByThermostatProgramId[thermostatProgramId],
+            }))
+                .filter((pair) => Boolean(pair.domusSensorId)),
+            manualCommandPairs: Object.entries(cache.thermostatProgramIdByOutputId)
+                .map(([outputId, thermostatProgramId]) => ({
+                thermostatOutputId: outputId,
+                commandThermostatId: thermostatProgramId,
+            })),
+        },
+        roomMapping: {
+            enabled: true,
+            rooms: [...roomDevices.entries()].map(([roomName, devices]) => ({
+                roomName,
+                devices: [...devices].map((deviceId) => ({ deviceId })),
+            })),
+        },
+        customNames: {
+            outputs: cache.outputNamesById,
+            zones: cache.zoneNamesById,
+            sensors: cache.domusSensorNamesById,
+            scenarios: cache.scenarioNamesById,
+        },
+        suggestedExclusions: {
+            outputs: [],
+            zones: [],
+            sensors: [],
+            scenarios: [],
+        },
+    };
+}
+function resolveRoomMapToDeviceIds(map, outputById) {
+    if (map.objectType === 'prgOutputs') {
+        const output = outputById.get(map.objectId);
+        if (!output) {
+            return [];
+        }
+        const outputType = (0, device_state_projector_1.determineOutputType)(output.CAT ?? '', output.MOD);
+        return [`${outputType}_${map.objectId}`];
+    }
+    if (map.objectType === 'prgZones') {
+        return [`zone_${map.objectId}`];
+    }
+    if (map.objectType === 'prgScenarios') {
+        return [`scenario_${map.objectId}`];
+    }
+    if (map.objectType === 'prgBusHas') {
+        return [`sensor_temp_${map.objectId}`, `sensor_hum_${map.objectId}`, `sensor_light_${map.objectId}`];
+    }
+    return [];
+}
+function toNameRecord(items) {
+    const record = {};
+    for (const item of items) {
+        const id = asId(item.ID);
+        if (!id) {
+            continue;
+        }
+        const name = normalizeLabel(item.DES);
+        if (name) {
+            record[id] = name;
+        }
+    }
+    return record;
+}
+function toRoomDeviceRefs(maps) {
+    return maps
+        .map((map) => ({
+        roomId: asId(map.ROOM),
+        objectType: normalizeLabel(map.OT) ?? '',
+        objectId: asId(map.OID),
+    }))
+        .filter((map) => Boolean(map.roomId) && Boolean(map.objectType) && Boolean(map.objectId));
+}
+function asId(value) {
+    if (typeof value === 'string') {
+        return value.trim();
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.trunc(value).toString();
+    }
+    return '';
+}
+function normalizeNullableId(value) {
+    const normalized = asId(value);
+    if (!normalized || normalized.toUpperCase() === 'NU' || normalized.toUpperCase() === 'NA') {
+        return null;
+    }
+    return normalized;
+}
+function normalizeLabel(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalized = value.trim();
+    return normalized ? normalized : null;
+}
+//# sourceMappingURL=derive.js.map

package/dist/ksa/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../src/ksa/derive.ts"],"names":[],"mappings":"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"}

package/dist/ksa/parser.d.ts

@@ -0,0 +1,4 @@
+import type { ParsedKsaProgram } from './types';
+export declare function readAndParseKsaProgram(filePath: string): Promise<ParsedKsaProgram>;
+export declare function parseKsaProgramFromBuffer(raw: Buffer): ParsedKsaProgram;
+//# sourceMappingURL=parser.d.ts.map

package/dist/ksa/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/ksa/parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAMhD,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAGxF;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAYvE"}