[feature]: allow to install node modules from GitHub url too

CHANGELOG.md

@@ -4,7 +4,7 @@
 	## __WORK IN PROGRESS__
 -->
 
-## 6.0.1 (2024-06-10) - Kiera
+## __WORK IN PROGRESS__ - Kiera
 
 **Breaking changes**
 * Support for Node.js 16 is dropped!

README.md

@@ -219,6 +219,7 @@ if (result.success) {
 }
 ```
 
+Instead of specifying a module name you can also specify a URL to e.g. install a package from GitHub.
 To use the installed node module, you can import it:
 
 ```typescript

packages/adapter/src/lib/_Types.ts

@@ -595,6 +595,6 @@ export interface InstallNodeModuleOptions {
 }
 
 export interface InternalInstallNodeModuleOptions extends InstallNodeModuleOptions {
-    /** Name of the npm module */
-    moduleName: string;
+    /** Name of the npm module or an installable url ẁorking with `npm install` */
+    moduleNameOrUrl: string;
 }

packages/adapter/src/lib/adapter/adapter.ts

@@ -22,7 +22,8 @@
     getSupportedFeatures,
     isMessageboxSupported,
     getAdapterScopedPackageIdentifier,
-    listInstalledNodeModules
+    listInstalledNodeModules,
+    requestModuleNameByUrl
 } from '@/lib/adapter/utils.js';
 // @ts-expect-error no ts file
 import extend from 'node.extend';
@@ -1249,21 +1250,30 @@
     /**
      * Install specified npm module
      *
-     * @param moduleName name of the node module
+     * @param moduleNameOrUrl name of the node module or GitHub url which can be passed to `npm install`
      * @param options version information
      */
-    installNodeModule(moduleName: unknown, options: unknown): Promise<CommandResult> {
-        Validator.assertString(moduleName, 'moduleName');
+    installNodeModule(moduleNameOrUrl: unknown, options: unknown): Promise<CommandResult> {
+        Validator.assertString(moduleNameOrUrl, 'moduleNameOrUrl');
         Validator.assertObject<InstallNodeModuleOptions>(options, 'options');
 
-        return this._installNodeModule({ ...options, moduleName });
+        return this._installNodeModule({ ...options, moduleNameOrUrl });
     }
 
-    private _installNodeModule(options: InternalInstallNodeModuleOptions): Promise<CommandResult> {
-        const { moduleName, version } = options;
+    private async _installNodeModule(options: InternalInstallNodeModuleOptions): Promise<CommandResult> {
+        const { moduleNameOrUrl, version } = options;
+
+        let moduleName = moduleNameOrUrl;
+        const isUrl = URL.canParse(moduleNameOrUrl);
+
+        if (isUrl) {
+            moduleName = await requestModuleNameByUrl(moduleNameOrUrl);
+        }
 
         const internalModuleName = getAdapterScopedPackageIdentifier({ moduleName, namespace: this.namespace });
-        return tools.installNodeModule(`${internalModuleName}@npm:${moduleName}@${version}`);
+        const packageIdentifier = isUrl ? moduleNameOrUrl : `npm:${moduleName}@${version}`;
+
+        return tools.installNodeModule(`${internalModuleName}@${packageIdentifier}`);
     }
 
     /**
@@ -1310,7 +1320,7 @@
      * Decrypt the password/value with given key
      *
      * @param secretVal to use for decrypt (or value if only one parameter is given)
-     * @param  [value] value to decrypt (if secret is provided)
+     * @param value value to decrypt (if secret is provided)
      */
     decrypt(secretVal: unknown, value?: unknown): string {
         if (value === undefined) {
@@ -1585,7 +1595,7 @@
      *         ...
      *     }
      * ```
 
      * @param featureName the name of the feature to check
      * @returns true/false if the feature is in the list of supported features
      */
@@ -5120,11 +5130,11 @@
     ): void;
 
     /**
      * @param deviceName
      * @param common
      * @param _native
      * @param options
      * @param callback
      * @deprecated use `this.extendObject` instead
      */
     createDevice(deviceName: unknown, common: unknown, _native?: unknown, options?: unknown, callback?: unknown): any {
@@ -5215,10 +5225,10 @@
     /**
      * Name of channel must be in format "channel"
      *
      * @param parentDevice
      * @param channelName
      * @param roleOrCommon
      * @param _native
      * @param options
      * @param callback
      * @deprecated use `this.extendObject` instead

packages/adapter/src/lib/adapter/utils.ts

@@ -4,7 +4,8 @@ import {
     encrypt,
     decrypt,
     appNameLowerCase,
-    getRootDir
+    getRootDir,
+    execAsync
 } from '@iobroker/js-controller-common-db/tools';
 import { SUPPORTED_FEATURES, type SupportedFeature } from '@/lib/adapter/constants.js';
 import path from 'node:path';
@@ -125,3 +126,20 @@ export async function listInstalledNodeModules(namespace: string): Promise<strin
 
     return dependencies;
 }
+
+/**
+ * Request a module name by given url using `npm view`
+ *
+ * @param url the url to the package which should be installed via npm
+ */
+export async function requestModuleNameByUrl(url: string): Promise<string> {
+    const res = await execAsync(`npm view ${url} name`);
+
+    if (typeof res.stdout !== 'string') {
+        throw new Error(
+            `Could not determine module name for url "${url}". Unexpected stdout: "${res.stdout ? res.stdout.toString() : ''}"`
+        );
+    }
+
+    return res.stdout.trim();
+}