homematic-manager 3.0.0-beta.4 → 3.0.0-beta.6

package/dist/cli.js

@@ -10,6 +10,7 @@
  */
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
+import { isLoopbackHost } from './auth.js';
 import { createWebHost } from './server.js';
 import { installService, uninstallService } from './install.js';
 import { createLogger } from './log.js';
@@ -93,6 +94,15 @@ export async function runCli(options = {}) {
         log.debug(`token ${host.token}`);
     }
     log.debug(`a client without a cookie can use ${host.url}?token=${host.token}`);
+    if (host.token !== undefined && host.issueCookie && !isLoopbackHost(parsed.host)) {
+        // D-41: the Docker image binds 0.0.0.0 and issues the cookie so that the UI works out of
+        // the box - which means whoever reaches the port is in. Said once, at start, with the ways
+        // out; the host cannot see a proxy or TLS in front of it, so it says this whenever it is
+        // in that position
+        log.warn(`the token cookie is handed to every browser that loads the page on ${parsed.host}: whoever reaches this port is in;` +
+            ' put a proxy with authentication and TLS in front, publish the port on the loopback only,' +
+            ' or set HMM_ISSUE_COOKIE=false and open the UI once with ?token=');
+    }
     if (parsed.authMode === 'rega') {
         // D-32: the token still works and `settings.cgi` still hands it out - the login is a second
         // door, not a replacement, and saying so keeps the addon's two paths straight in the log

package/dist/server.d.ts

@@ -142,6 +142,8 @@ export interface WebHost {
     readonly base: string;
     /** `undefined` when auth is off. */
     readonly token: string | undefined;
+    /** Whether the page load hands the token to the browser as a cookie (D-41 says when to warn). */
+    readonly issueCookie: boolean;
     /** D-32: how a browser is let in. */
     readonly authMode: AuthMode;
     /** D-32/D-40: the login sessions; `undefined` in `token` mode, where there are none. */

package/dist/server.js

@@ -465,6 +465,7 @@ export async function createWebHost(options = {}) {
         port,
         base,
         token,
+        issueCookie,
         authMode,
         sessions,
         close,

package/node_modules/@homematic-manager/backend/dist/api/backend.js

@@ -342,6 +342,11 @@ export class Backend {
             case 'meta.node.delete':
                 await (await this.#requireMeta()).deleteNode(p[0], p[1] === true);
                 return null;
+            case 'meta.refresh': {
+                const meta = await this.#requireMeta();
+                await meta.refresh();
+                return meta.state();
+            }
             case 'meta.export':
                 return (await this.#requireMeta()).document();
             case 'meta.import':
@@ -540,6 +545,14 @@ export class Backend {
                 cacheDir: this.#config.cacheDir,
                 names: this.#caches.names,
                 interfaceOf: (address) => this.#interfaceOf(address),
+                // task 27: ReGa as the store of rooms and functions on a CCU. Read through the
+                // service that is current at call time - a reconnect replaces it.
+                rega: this.#rega === undefined || !connection.rega
+                    ? undefined
+                    : {
+                        available: this.#rega.available,
+                        exec: (script) => this.#requireRega().exec(script),
+                    },
                 onChanged: () => {
                     this.#onMetaChanged();
                 },
@@ -567,6 +580,12 @@ export class Backend {
             this.#notice('warn', `the metadata store could not be opened: ${errorMessage(error)}`);
         }
     }
+    #requireRega() {
+        if (!this.#rega) {
+            throw configError('ReGa is not connected');
+        }
+        return this.#rega;
+    }
     /** The store changed - locally, or on the box because somebody else edited it. */
     #onMetaChanged() {
         const meta = this.#meta;
@@ -869,7 +888,22 @@ export class Backend {
     async #setNames(entries) {
         const written = this.#caches.names.set(entries);
         this.#caches.saveNames();
-        await this.#rega?.rename(written);
+        // task 27: with ReGa as the metadata store the provider writes the rename itself, and a
+        // second `Name()` through the name service would be the same script twice - but only for
+        // the objects the provider holds, and only while ReGa answers it; anything else still goes
+        // the way it always did (found by the e2e suite: a rename lost for good is worse than one
+        // script twice)
+        const meta = this.#meta;
+        const held = meta?.kind === 'rega' && meta.state().reachable ? meta.document().objects : undefined;
+        const throughNames = held === undefined
+            ? written
+            : written.filter((entry) => {
+                const ref = meta?.refFor(entry.address);
+                return ref === undefined || !(ref in held);
+            });
+        if (throughNames.length > 0) {
+            await this.#rega?.rename(throughNames);
+        }
         // D-40: and into the metadata store, which on an openccu-lite box is the box's own. The
         // local cache is written first either way, so a store that refuses the write still leaves
         // the name where the user typed it - and the refusal is reported rather than swallowed.
@@ -884,7 +918,10 @@ export class Backend {
     /** The state, even before a connection exists - the settings dialog asks for it either way. */
     #metaState() {
         return (this.#meta?.state() ?? {
-            provider: this.#config.connection.metaProvider === 'occulite' ? 'occulite' : 'local',
+            provider: this.#config.connection.metaProvider === 'occulite' ||
+                this.#config.connection.metaProvider === 'rega'
+                ? this.#config.connection.metaProvider
+                : 'local',
             reachable: false,
             writable: false,
             revision: 0,
@@ -1325,6 +1362,7 @@ export const API_METHOD_NAMES = [
     'meta.node.create',
     'meta.node.update',
     'meta.node.delete',
+    'meta.refresh',
     'meta.export',
     'meta.import',
     'paramset.get',

package/node_modules/@homematic-manager/backend/dist/meta/index.d.ts

@@ -7,5 +7,6 @@ export * from './credentials.js';
 export * from './provider.js';
 export * from './localProvider.js';
 export * from './occuliteProvider.js';
+export * from './regaProvider.js';
 export * from './service.js';
 //# sourceMappingURL=index.d.ts.map

package/node_modules/@homematic-manager/backend/dist/meta/index.js

@@ -7,5 +7,6 @@ export * from './credentials.js';
 export * from './provider.js';
 export * from './localProvider.js';
 export * from './occuliteProvider.js';
+export * from './regaProvider.js';
 export * from './service.js';
 //# sourceMappingURL=index.js.map

package/node_modules/@homematic-manager/backend/dist/meta/provider.d.ts

@@ -6,10 +6,11 @@
  * openccu-lite box, follows its change stream and **writes back**, because on that box this
  * application is the editor of the store: there is no ReGaHSS and no WebUI to do it instead.
  *
- * The ReGa path is untouched by all of this (their invariant 1, our D-2): ReGa still supplies names
- * on a CCU, still writes a rename back through its script, and a box that has ReGa never has a
- * metadata API. What the provider adds is the taxonomy ReGa's rooms and functions were, for the
- * systems that have no ReGa at all.
+ * `rega` (task 27) is the third: on a CCU with ReGaHSS the rooms and functions are ReGa's own enum
+ * objects, read and written through the script transport the names already use, so that one
+ * editing UI serves a CCU and a box. A box that has ReGa never has a metadata API, so the three
+ * never compete: the box's API wins when it answers, ReGa when it is on and answered, and `local`
+ * is what every other system - Homegear, a bare rfd, the desktop without a CCU - gets.
  */
 import type { MetaDocument, MetaEnum, MetaImportMode, MetaNodePatch, MetaState } from '@homematic-manager/core';
 /** One name to write: the store's identity is the ref, not the bare address. */
@@ -34,7 +35,7 @@ export interface MetaProviderEvents {
  * box on the network; every read is synchronous because both keep the document in memory.
  */
 export interface MetadataProvider {
-    readonly kind: 'local' | 'occulite';
+    readonly kind: 'local' | 'occulite' | 'rega';
     state(): MetaState;
     /** Loads the document (a file, or the box's snapshot) and starts following changes. */
     start(): Promise<void>;

package/node_modules/@homematic-manager/backend/dist/meta/provider.js

@@ -6,10 +6,11 @@
  * openccu-lite box, follows its change stream and **writes back**, because on that box this
  * application is the editor of the store: there is no ReGaHSS and no WebUI to do it instead.
  *
- * The ReGa path is untouched by all of this (their invariant 1, our D-2): ReGa still supplies names
- * on a CCU, still writes a rename back through its script, and a box that has ReGa never has a
- * metadata API. What the provider adds is the taxonomy ReGa's rooms and functions were, for the
- * systems that have no ReGa at all.
+ * `rega` (task 27) is the third: on a CCU with ReGaHSS the rooms and functions are ReGa's own enum
+ * objects, read and written through the script transport the names already use, so that one
+ * editing UI serves a CCU and a box. A box that has ReGa never has a metadata API, so the three
+ * never compete: the box's API wins when it answers, ReGa when it is on and answered, and `local`
+ * is what every other system - Homegear, a bare rfd, the desktop without a CCU - gets.
  */
 /** The enums of a document, for a caller that only wants the trees. */
 export function enumsOf(document) {

package/node_modules/@homematic-manager/backend/dist/meta/regaProvider.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The `rega` metadata provider (task 27): the CCU's own rooms and functions, through ReGaHSS.
+ *
+ * On a CCU the rooms and functions the user sees in the WebUI live in ReGa's DOM - enum objects
+ * under `ID_ROOMS` and `ID_FUNCTIONS`, each holding channel ids - and a taxonomy kept in this
+ * profile beside them would be a second truth. So on a CCU with ReGa this provider *is* the store:
+ * the same {@link MetadataProvider} surface the box's provider has, over the same script transport
+ * the names already use, so that the editing UI of task 25 does not know which one it talks to.
+ *
+ * What ReGa's model is, and therefore what this provider is:
+ *
+ * - **Flat.** A room is a room; there is no room below another and no floor. `state().flat` says
+ *   so, `createNode` with a parent and a move under a parent are refused.
+ * - **Two taxonomies, fixed.** Rooms and functions exist; nothing else can be created or deleted.
+ * - **Channels are members, devices are not.** The WebUI assigns channels. A device ref in a
+ *   membership write is applied to every channel of the device except the `:0` maintenance
+ *   channel, which is what a user who "puts the device in the kitchen" means.
+ * - **Identity is the ReGa id.** A node's id is `r<id>`, stable across renames, so a path never
+ *   has to be rewritten when a room is renamed.
+ * - **No change stream.** ReGa tells nobody when the WebUI edits a room. This provider reads
+ *   everything on `start()`, after every write of its own, and on `refresh()`, which the UI asks
+ *   for through `meta.refresh`.
+ *
+ * Failure is a state, never an exception (D-2): a script that does not run leaves the last
+ * document in place, sets `reachable: false` and says so once.
+ */
+import { type Language, type MetaDocument, type MetaNodePatch, type MetaState } from '@homematic-manager/core';
+import type { MetadataProvider, MetaMembershipEntry, MetaNameEntry, MetaProviderEvents } from './provider.js';
+/** The part of the ReGa transport this provider uses: run a script, read what it wrote. */
+export type RegaScriptRunner = (script: string) => Promise<{
+    output: string;
+}>;
+export interface RegaMetaProviderOptions extends MetaProviderEvents {
+    readonly exec: RegaScriptRunner;
+    /**
+     * The interface an address belongs to, from the device caches - the fallback for a device
+     * whose interface ReGa does not name (an older firmware, a CUxD device).
+     */
+    readonly interfaceOf: (address: string) => string | undefined;
+    /**
+     * The language the stock rooms and functions are shown in. ReGa stores them as translation keys
+     * (`roomKitchen`) and the WebUI translates them on display; the CCU's own default is German.
+     */
+    readonly language?: Language | undefined;
+}
+/**
+ * The rooms and functions a CCU comes with, as the WebUI translates them (`translate.lang.js` of
+ * the German and the English WebUI, firmware 3.89.8). ReGa's objects carry the *key* as their
+ * `Name()` - `roomKitchen`, not `Küche` - and every WebUI page translates it on display, so a list
+ * that shows the keys is not what the user sees on the CCU. Found in the first lab pass of task 27.
+ * A name that is not one of these keys is shown as it is; a rename writes the literal name.
+ */
+export declare const REGA_STOCK_NAMES: Readonly<Record<string, Readonly<Record<'de' | 'en', string>>>>;
+/** `roomKitchen` -> `Küche`; anything that is not a stock key is answered as it is. */
+export declare function regaStockName(name: string, language: Language | undefined): string;
+/** `r4711` - the node id of a ReGa enum object; stable across renames. */
+export declare function regaNodeId(id: number): string;
+/** The ReGa id behind a node id, or `undefined` for anything that is not one. */
+export declare function parseRegaNodeId(id: string): number | undefined;
+export declare class RegaMetaProvider implements MetadataProvider {
+    #private;
+    readonly kind: "rega";
+    constructor(options: RegaMetaProviderOptions);
+    state(): MetaState;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Reads everything again. Never throws: a ReGa that does not answer is a state. */
+    refresh(): Promise<void>;
+    document(): MetaDocument;
+    setNames(entries: readonly MetaNameEntry[]): Promise<void>;
+    setMembership(entries: readonly MetaMembershipEntry[]): Promise<void>;
+    createEnum(): Promise<void>;
+    updateEnum(): Promise<void>;
+    deleteEnum(): Promise<void>;
+    /**
+     * A new room or function. The id the caller derived from the name is not used: ReGa hands out
+     * the id, and `r<id>` is what keeps the path stable when the room is renamed later.
+     */
+    createNode(enumId: string, parent: string | null, _id: string, name: string): Promise<string>;
+    updateNode(path: string, patch: MetaNodePatch): Promise<void>;
+    deleteNode(path: string, detach: boolean): Promise<void>;
+    import(): Promise<void>;
+}
+//# sourceMappingURL=regaProvider.d.ts.map