@iobroker/js-controller-cli 7.2.5 → 8.0.0-alpha.11-20261103-58da667b3

package/build/esm/lib/setup/setupInstall.js

@@ -6,25 +6,30 @@
  *      MIT License
  *
  */
-import { tools, EXIT_CODES } from '@iobroker/js-controller-common';
-import fs from 'fs-extra';
 import path from 'node:path';
-import semver from 'semver';
 import child_process from 'node:child_process';
-import axios from 'axios';
 import { URL } from 'node:url';
+import { createRequire } from 'node:module';
+import axios from 'axios';
+import fs from 'fs-extra';
+import semver from 'semver';
+import { tools, EXIT_CODES } from '@iobroker/js-controller-common';
 import { Upload } from '../../lib/setup/setupUpload.js';
 import { PacketManager } from '../../lib/setup/setupPacketManager.js';
 import { getRepository } from '../../lib/setup/utils.js';
 import { IoBrokerError } from '../../lib/setup/customError.js';
+import { dbConnect } from '../../lib/setup/dbConnection.js';
+import * as CLITools from '../../lib/cli/cliTools.js';
 import { SYSTEM_ADAPTER_PREFIX } from '@iobroker/js-controller-common-db/constants';
-import { createRequire } from 'node:module';
 // eslint-disable-next-line unicorn/prefer-module
 const require = createRequire(import.meta.url || `file://${__filename}`);
 const hostname = tools.getHostName();
 const osPlatform = process.platform;
 /** Note: this is duplicated in preinstallCheck */
 const RECOMMENDED_NPM_VERSION = 8;
+/**
+ * CLI command to install and download adapters and create their instances
+ */
 export class Install {
     isRootOnUnix;
     objects;
@@ -34,6 +39,9 @@ export class Install {
     tarballRegex;
     upload;
     packetManager;
+    /**
+     * @param options The states/objects clients, CLI parameters and the process-exit callback
+     */
     constructor(options) {
         this.isRootOnUnix = typeof process.getuid === 'function' && process.getuid() === 0;
         options = options || {};
@@ -88,7 +96,7 @@ export class Install {
         if (!options || typeof options !== 'object') {
             options = {};
         }
-        stoppedList = stoppedList || [];
+        stoppedList ||= [];
         let sources;
         if (!repoUrlOrRepo || !tools.isObject(repoUrlOrRepo)) {
             sources = await getRepository({ repoName: repoUrlOrRepo, objects: this.objects });
@@ -465,7 +473,7 @@ export class Install {
                 obj.from = `system.host.${hostname}.cli`;
                 obj.ts = Date.now();
                 try {
-                    await this.objects.extendObjectAsync(obj._id, obj);
+                    await this.objects.extendObject(obj._id, obj);
                 }
                 catch (err) {
                     console.error(`host.${hostname} error setObject ${obj._id} ${err.message}`);
@@ -479,8 +487,8 @@ export class Install {
      * Installs given adapter
      *
      * @param adapter The adapter name
-     * @param repoUrl
-     * @param _installCount
+     * @param repoUrl Optional repository URL to install the adapter from
+     * @param _installCount Internal recursion counter limiting the number of dependency installs
      */
     async installAdapter(adapter, repoUrl, _installCount) {
         _installCount = _installCount || 0;
@@ -547,6 +555,11 @@ export class Install {
         await this.upload.upgradeAdapterObjects(adapter);
         return adapter;
     }
+    /**
+     * Install the OS packages required by an adapter
+     *
+     * @param osDependencies The OS dependencies declared by the adapter, keyed by platform
+     */
     async installOSPackages(osDependencies) {
         if (osPlatform in osDependencies) {
             try {
@@ -560,6 +573,12 @@ export class Install {
             }
         }
     }
+    /**
+     * Run the custom install script of an adapter if it defines one
+     *
+     * @param adapter The adapter name
+     * @param config The adapter object containing the install configuration
+     */
     async callInstallOfAdapter(adapter, config) {
         if (config.common.install) {
             // Install node modules
@@ -815,10 +834,10 @@ export class Install {
     /**
      * Enumerate all instances of an adapter
      *
-     * @param knownObjIDs
-     * @param notDeleted
-     * @param adapter
-     * @param instance
+     * @param knownObjIDs Accumulator of object IDs found so far
+     * @param notDeleted Accumulator of object IDs that must not be deleted
+     * @param adapter The adapter name
+     * @param instance Optional instance number to restrict the search to
      */
     async _enumerateAdapterInstances(knownObjIDs, notDeleted, adapter, instance) {
         if (!notDeleted) {
@@ -868,9 +887,9 @@ export class Install {
     /**
      * Enumerate all meta objects of an adapter
      *
-     * @param knownObjIDs
-     * @param adapter
-     * @param metaFilesToDelete
+     * @param knownObjIDs Accumulator of object IDs found so far
+     * @param adapter The adapter name
+     * @param metaFilesToDelete Accumulator of meta files that should be deleted
      */
     async _enumerateAdapterMeta(knownObjIDs, adapter, metaFilesToDelete) {
         try {
@@ -1077,9 +1096,9 @@ export class Install {
     /**
      * Enumerate all state IDs of an adapter (or instance)
      *
-     * @param knownStateIDs
-     * @param adapter
-     * @param instance
+     * @param knownStateIDs Accumulator of state IDs found so far
+     * @param adapter The adapter name
+     * @param instance Optional instance number to restrict the search to
      */
     async _enumerateAdapterStates(knownStateIDs, adapter, instance) {
         for (const pattern of [
@@ -1108,8 +1127,8 @@ export class Install {
     /**
      * delete WWW pages, objects and meta files
      *
-     * @param adapter
-     * @param metaFilesToDelete
+     * @param adapter The adapter name
+     * @param metaFilesToDelete The meta files that should be deleted
      */
     async _deleteAdapterFiles(adapter, metaFilesToDelete) {
         // special files, which are not meta (vis widgets), combined with meta object ids
@@ -1277,6 +1296,7 @@ export class Install {
                 // remove adapter from custom
                 await this._removeCustomFromObjects([adapter]);
                 await _uninstallNpm();
+                await this._removePythonEnvironment(adapter);
             }
             else {
                 // we are not allowed to delete the last instance if another instance depends on us
@@ -1296,11 +1316,15 @@ export class Install {
                 await this._deleteAdapterFiles(adapter, metaFilesToDelete);
                 await this._deleteAdapterObjects(knownObjectIDs);
                 await this._deleteAdapterStates(knownStateIDs);
+                // this path removes the instance objects itself instead of going through deleteInstance,
+                // so the registry entries of every instance of the adapter have to be freed here as well
+                await this._freeUsedResources(adapter);
                 if (this.params.custom) {
                     // remove adapter from custom
                     await this._removeCustomFromObjects([...instances, adapter]);
                 }
                 await _uninstallNpm();
+                await this._removePythonEnvironment(adapter);
             }
         }
         catch (e) {
@@ -1308,6 +1332,32 @@ export class Install {
         }
         return resultCode;
     }
+    /**
+     * Remove the virtual environment a Python adapter leaves behind in the data directory
+     *
+     * Host-local state like `node_modules` - rebuildable, but easily a few hundred megabytes - so it goes when
+     * the adapter goes. Deliberately not part of the npm uninstall: that one starts by resolving the adapter's
+     * `io-package.json`, so for a half-removed installation, where the package directory is already gone, it
+     * throws before ever getting here - and that is precisely the case which leaves the environment behind with
+     * nothing pointing at it.
+     *
+     * Removed without looking at `common.platform` for the same reason: the directory only exists for Python
+     * adapters, and the `io-package.json` that would say so may no longer be there.
+     *
+     * @param adapter adapter name, e.g. "pyexample"
+     */
+    async _removePythonEnvironment(adapter) {
+        try {
+            const pythonEnvDir = tools.getPythonEnvDir(adapter);
+            if (await fs.pathExists(pythonEnvDir)) {
+                await fs.remove(pythonEnvDir);
+                console.log(`host.${hostname} Python environment "${pythonEnvDir}" deleted`);
+            }
+        }
+        catch (e) {
+            console.error(`Cannot delete the Python environment of ${adapter}: ${e.message}`);
+        }
+    }
     /**
      * Deletes given instance of an adapter
      *
@@ -1332,11 +1382,89 @@ export class Install {
         await this._enumerateAdapterDocs(knownObjectIDs, adapter, instance);
         await this._deleteAdapterObjects(knownObjectIDs);
         await this._deleteAdapterStates(knownStateIDs);
+        await this._freeUsedResources(adapter, instance);
         if (this.params.custom) {
             // delete instance from custom
             await this._removeCustomFromObjects([`${adapter}.${instance}`]);
         }
     }
+    /**
+     * Free all exclusive resources (serial ports, TCP/UDP ports, ...) the given instance(s) had registered.
+     *
+     * This is needed because an instance can be deleted via the CLI while a js-controller is not running: it
+     * cannot notice that the instance object disappeared, so its `system.host.<host>.usedResources.<type>`
+     * states would keep listing the resources of an instance that no longer exists.
+     *
+     * Hosts that are running are deliberately skipped. Such a host cleans its own registry up when it sees the
+     * instance object being deleted, and it holds the registry in memory: it rewrites the state from that copy
+     * on its next change, which would silently undo a write made here.
+     *
+     * @param adapter adapter name, e.g. "mqtt"
+     * @param instance instance number; if undefined, all instances of the adapter are freed
+     */
+    async _freeUsedResources(adapter, instance) {
+        const matches = (namespace) => instance !== undefined ? namespace === `${adapter}.${instance}` : namespace.startsWith(`${adapter}.`);
+        let keys;
+        try {
+            keys = await this.states.getKeys('system.host.*.usedResources.*');
+        }
+        catch (e) {
+            console.warn(`Cannot read the used resources registry: ${e.message}`);
+            return;
+        }
+        if (!keys?.length) {
+            return;
+        }
+        const hostPrefix = 'system.host.';
+        const registryMarker = '.usedResources.';
+        /** whether a host is currently running, queried once per host */
+        const hostIsRunning = new Map();
+        for (const id of keys) {
+            const markerIndex = id.lastIndexOf(registryMarker);
+            if (!id.startsWith(hostPrefix) || markerIndex <= hostPrefix.length) {
+                continue;
+            }
+            const host = id.substring(hostPrefix.length, markerIndex);
+            let isRunning = hostIsRunning.get(host);
+            if (isRunning === undefined) {
+                try {
+                    const aliveState = await this.states.getState(`${hostPrefix}${host}.alive`);
+                    isRunning = aliveState?.val === true;
+                }
+                catch (e) {
+                    // if it cannot be determined, assume the host is running: leaving an entry behind is
+                    // harmless (its controller drops it on the next start) while fighting a live controller
+                    // over the same state is not
+                    console.warn(`Cannot check whether host "${host}" is running: ${e.message}`);
+                    isRunning = true;
+                }
+                hostIsRunning.set(host, isRunning);
+            }
+            if (isRunning) {
+                continue;
+            }
+            try {
+                const state = await this.states.getState(id);
+                if (!state || typeof state.val !== 'string' || !state.val) {
+                    continue;
+                }
+                const parsed = JSON.parse(state.val);
+                if (!Array.isArray(parsed)) {
+                    continue;
+                }
+                const original = parsed;
+                // keep anything that is malformed: it cannot be attributed to the deleted instance, and one
+                // broken entry must not stop the cleanup of the sound ones in the same state
+                const filtered = original.filter(entry => typeof entry?.instance !== 'string' || !matches(entry.instance));
+                if (filtered.length !== original.length) {
+                    await this.states.setStateAsync(id, { val: JSON.stringify(filtered), ack: true });
+                }
+            }
+            catch (e) {
+                console.warn(`Cannot free the used resources in "${id}": ${e.message}`);
+            }
+        }
+    }
     /**
      * Remove all node modules that has been installed by this instance
      *
@@ -1625,4 +1753,189 @@ export class Install {
         return instances;
     }
 }
+/**
+ * @param options options provided by the processCommand dispatcher
+ */
+export function processCommandUrl(options) {
+    const { args, params, callback } = options;
+    let url = args[0];
+    const name = args[1];
+    if (!url) {
+        console.log('Please provide a URL to install from and optionally a name of the adapter to install');
+        return void callback(EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    if (url[0] === '"' && url[url.length - 1] === '"') {
+        url = url.substring(1, url.length - 1);
+    }
+    url = url.trim();
+    dbConnect(params, async ({ objects, states }) => {
+        const install = new Install({
+            objects,
+            states,
+            processExit: callback,
+            params,
+        });
+        try {
+            await install.installAdapterFromUrl(url, name);
+            return void callback(EXIT_CODES.NO_ERROR);
+        }
+        catch (e) {
+            console.error(`Could not install adapter from url: ${e.message}`);
+            return void callback(EXIT_CODES.CANNOT_INSTALL_NPM_PACKET);
+        }
+    });
+}
+/**
+ * @param options options provided by the processCommand dispatcher
+ */
+export function processCommandInstall(options) {
+    const { command, args, params, callback } = options;
+    const { showHelp } = options.commandOptions;
+    let name = args[0];
+    let instance = args[1];
+    let repoUrl = args[2];
+    if (parseInt(instance, 10).toString() !== (instance || '').toString()) {
+        repoUrl = instance;
+        instance = undefined;
+    }
+    if (parseInt(repoUrl, 10).toString() === (repoUrl || '').toString()) {
+        const temp = instance;
+        instance = repoUrl;
+        repoUrl = temp;
+    }
+    if (instance && parseInt(instance, 10).toString() === (instance || '').toString()) {
+        params.instance = parseInt(instance, 10);
+    }
+    // If user accidentally wrote tools.appName.adapter => remove adapter
+    name = CLITools.normalizeAdapterName(name);
+    const parsedName = CLITools.splitAdapterOrInstanceIdentifierWithVersion(name);
+    if (!parsedName) {
+        console.log('Invalid adapter name for install');
+        showHelp();
+        return void callback(EXIT_CODES.INVALID_ADAPTER_ID);
+    }
+    // split the adapter into its parts if necessary
+    if (parsedName.instance !== null) {
+        params.instance = parsedName.instance;
+    }
+    name = parsedName.name;
+    const installName = parsedName.nameWithVersion;
+    const adapterDir = tools.getAdapterDir(name);
+    dbConnect(params, async ({ objects, states }) => {
+        const install = new Install({
+            objects,
+            states,
+            processExit: callback,
+            params,
+        });
+        if (params.host && params.host !== tools.getHostName()) {
+            // if host argument provided we should check, that host actually exists in mh environment
+            let obj;
+            try {
+                obj = await objects.getObjectAsync(`system.host.${params.host}`);
+            }
+            catch (err) {
+                console.warn(`Could not check existence of host "${params.host}": ${err.message}`);
+            }
+            if (!obj) {
+                console.error(`Cannot add instance to non-existing host "${params.host}"`);
+                return void callback(EXIT_CODES.NON_EXISTING_HOST);
+            }
+        }
+        if (!adapterDir || !fs.existsSync(adapterDir)) {
+            try {
+                const { stoppedList } = await install.downloadPacket(repoUrl, installName);
+                await install.installAdapter(installName, repoUrl);
+                await install.enableInstances(stoppedList, true); // even if unlikely make sure to re-enable disabled instances
+                if (command !== 'install' && command !== 'i') {
+                    await install.createInstance(name, params);
+                }
+                return void callback();
+            }
+            catch (e) {
+                console.error(`adapter "${name}" cannot be installed: ${e.message}`);
+                return void callback(e instanceof IoBrokerError ? e.code : EXIT_CODES.UNKNOWN_ERROR);
+            }
+        }
+        else if (command !== 'install' && command !== 'i') {
+            try {
+                await install.createInstance(name, params);
+                return void callback();
+            }
+            catch (err) {
+                console.error(`adapter "${name}" cannot be installed: ${err.message}`);
+                return void callback(EXIT_CODES.UNKNOWN_ERROR);
+            }
+        }
+        else {
+            console.log(`adapter "${name}" already installed. Use "upgrade" to upgrade to a newer version.`);
+            return void callback(EXIT_CODES.ADAPTER_ALREADY_INSTALLED);
+        }
+    });
+}
+/**
+ * @param options options provided by the processCommand dispatcher
+ */
+export function processCommandDelete(options) {
+    const { args, params, callback } = options;
+    const { showHelp } = options.commandOptions;
+    let adapter = args[0];
+    let instance = args[1];
+    // The adapter argument is required
+    if (!adapter) {
+        showHelp();
+        return void callback(EXIT_CODES.INVALID_ADAPTER_ID);
+    }
+    // If the user accidentally wrote <tools.appName>.adapter,
+    // remove <tools.appName> from the adapter name
+    adapter = CLITools.normalizeAdapterName(adapter);
+    // Avoid deleting stuff we don't want to delete
+    // e.g. `system.adapter.*`
+    if (!instance) {
+        // Ensure that adapter contains a valid adapter (without instance nr)
+        // or instance (with instance nr) identifier
+        if (!CLITools.validateAdapterOrInstanceIdentifier(adapter)) {
+            showHelp();
+            return void callback(EXIT_CODES.INVALID_ADAPTER_ID);
+        }
+        // split the adapter into adapter + instance if necessary
+        if (adapter.indexOf('.') > -1) {
+            [adapter, instance] = adapter.split('.', 2);
+        }
+    }
+    else {
+        // ensure that adapter contains a valid adapter identifier
+        // and the instance is a number
+        if (!CLITools.validateAdapterIdentifier(adapter) || !/^\d+$/.test(instance)) {
+            showHelp();
+            return void callback(EXIT_CODES.INVALID_ADAPTER_ID);
+        }
+    }
+    if (instance) {
+        dbConnect(params, async ({ objects, states }) => {
+            const install = new Install({
+                objects,
+                states,
+                processExit: callback,
+                params,
+            });
+            console.log(`Delete instance "${adapter}.${instance}"`);
+            await install.deleteInstance(adapter, parseInt(instance));
+            callback();
+        });
+    }
+    else {
+        dbConnect(params, async ({ objects, states }) => {
+            const install = new Install({
+                objects,
+                states,
+                processExit: callback,
+                params,
+            });
+            console.log(`Delete adapter "${adapter}"`);
+            const resultCode = await install.deleteAdapter(adapter);
+            callback(resultCode);
+        });
+    }
+}
 //# sourceMappingURL=setupInstall.js.map