Added readme attribute to the adapter object (#2848)

* Added readme attribute to the adapter object

* Comments checking

---------

Co-authored-by: Max Hauser <[email protected]>

Author: GermanBluefox

packages/cli/src/lib/setup/setupInstall.ts

@@ -1,7 +1,7 @@
 /**
  *      Install adapter
  *
- *      Copyright 2013-2023 bluefox <[email protected]>
+ *      Copyright 2013-2024 bluefox <[email protected]>
  *
  *      MIT License
  *
@@ -187,7 +187,7 @@ export class Install {
             packetName = parts[0];
             version = parts[1];
         } else {
-            // always take version from repository
+            // always take a version from repository
             if (sources[packetName]?.version) {
                 version = sources[packetName].version;
             } else {
@@ -272,7 +272,7 @@ export class Install {
         }
 
         console.error(
-            `host.${hostname} Unknown packetName ${packetName}. Please install packages from outside the repository using "${tools.appNameLowerCase} url <url-or-package>"!`
+            `host.${hostname} Unknown packet name ${packetName}. Please install packages from outside the repository using "${tools.appNameLowerCase} url <url-or-package>"!`
         );
         throw new IoBrokerError({
             code: EXIT_CODES.UNKNOWN_PACKET_NAME,
@@ -359,7 +359,7 @@ export class Install {
             npmUrl = npmUrl.substring(0, npmUrl.indexOf('#'));
         }
         if (npmUrl.includes('/') && !npmUrl.startsWith('@')) {
-            // only scoped packages (e.g. @types/node ) may have a slash in their path
+            // only scoped packages (e.g., @types/node) may have a slash in their path
             npmUrl = npmUrl.substring(npmUrl.lastIndexOf('/') + 1);
         }
         if (!npmUrl.startsWith('@')) {
@@ -397,7 +397,7 @@ export class Install {
             unsafePerm: !!options.unsafePerm
         });
 
-        // code 1 is sometimes a real error and sometimes a strange error, where everything is installed but error
+        // code 1 is sometimes a real error and sometimes a strange error, where everything is installed but still the error
         const isSuccess = result.success || (result.exitCode === 1 && !result.stderr.startsWith('npm ERR!'));
 
         if (isSuccess) {
@@ -530,7 +530,7 @@ export class Install {
 
                 if (dName === 'js-controller') {
                     const version = allDeps[dName];
-                    // Check only if version not *, else we dont have to read io-pack unnecessarily
+                    // Check only if version not *, else we don't have to read io-pack unnecessarily
                     if (version !== '*') {
                         const packJson = fs.readJSONSync(`${tools.getControllerDir()}/package.json`);
                         if (!semver.satisfies(packJson.version, version, { includePrerelease: true })) {
@@ -554,7 +554,7 @@ export class Install {
                         gInstances = objs.rows.filter(obj => obj.value.common && obj.value.common.name === dName);
                     }
                     if (deps[dName] !== undefined) {
-                        // local dep get all instances on same host
+                        // local dependencies: get all instances on the same host
                         locInstances = objs.rows.filter(
                             obj =>
                                 obj.value.common &&
@@ -566,7 +566,7 @@ export class Install {
                         }
                     }
 
-                    // we check, that all existing instances match - respect different versions for local and global deps
+                    // we check that all existing instances match - respect different versions for local and global deps
                     for (const instance of locInstances) {
                         const instanceVersion = instance.value.common.version;
                         if (
@@ -698,7 +698,7 @@ export class Install {
 
             const { stoppedList } = await this.downloadPacket(repoUrl, fullName);
             await this.installAdapter(adapter, repoUrl, _installCount);
-            await this.enableInstances(stoppedList, true); // even if unlikely make sure to reenable disabled instances
+            await this.enableInstances(stoppedList, true); // even if unlikely make sure to re-enable disabled instances
             return adapter;
         }
         let adapterConf: ioBroker.AdapterObject;
@@ -1097,7 +1097,7 @@ export class Install {
                 .filter(row => !!row.value._id)
                 //  ... that matches the pattern
                 .filter(row => instanceRegex.test(row.value._id))
-                // if instance given also delete from foreign host else only instance on this host
+                // if instance given, also delete it from foreign host else only instance on this host
                 .filter(row => {
                     if (instance !== undefined || !row.value.common?.host || row.value.common?.host === hostname) {
                         return true;
@@ -1471,14 +1471,14 @@ export class Install {
 
         while (stateIDs.length > 0) {
             if (stateIDs.length % 200 === 0) {
-                // write progress report
+                // write a progress report
                 console.log(`host.${hostname}: Only ${stateIDs.length} states left to be deleted.`);
             }
             // try to delete the current state
             try {
                 await this.states.delState(stateIDs.pop()!);
             } catch (e) {
-                // yep that works!
+                // yep, that works!
                 e !== tools.ERRORS.ERROR_NOT_FOUND &&
                     e.message !== tools.ERRORS.ERROR_NOT_FOUND &&
                     console.error(`host.${hostname} Cannot delete states: ${e.message}`);
@@ -1506,7 +1506,7 @@ export class Install {
 
         while (objIDs.length > 0) {
             if (objIDs.length % 200 === 0) {
-                // write progress report
+                // write a progress report
                 console.log(`host.${hostname}: Only ${objIDs.length} objects left to be deleted.`);
             }
             // try to delete the current object
@@ -1543,7 +1543,7 @@ export class Install {
 
                 if (!ioPack.common || !ioPack.common.nondeletable) {
                     await this._npmUninstall(adapterNpm, false);
-                    // after uninstalling we have to restart the defined adapters
+                    // after uninstalling, we have to restart the defined adapters
                     if (ioPack.common.restartAdapters) {
                         if (!Array.isArray(ioPack.common.restartAdapters)) {
                             // it's not an array, now it can only be a single adapter as string
@@ -1602,7 +1602,7 @@ export class Install {
                 await this._removeCustomFromObjects([adapter]);
                 await _uninstallNpm();
             } else {
-                // we are not allowed to delete last instance if another instance depends on us
+                // we are not allowed to delete the last instance if another instance depends on us
                 const dependentInstance = await this._hasDependentInstances(adapter);
 
                 if (dependentInstance) {
@@ -1649,7 +1649,7 @@ export class Install {
         const knownObjectIDs: string[] = [];
         const knownStateIDs: string[] = [];
 
-        // we are not allowed to delete last instance if another instance depends on us
+        // we are not allowed to delete the last instance if another instance depends on us
         const dependentInstance = await this._hasDependentInstances(adapter, instance);
 
         if (dependentInstance) {
@@ -1677,7 +1677,7 @@ export class Install {
     }
 
     /**
-     * Remove all node modules which has been installed by this instance
+     * Remove all node modules that has been installed by this instance
      *
      * @param adapter adapter name like hm-rpc
      * @param instance e.g. 1, if undefined deletes all instances
@@ -1703,7 +1703,7 @@ export class Install {
      * @param ids - id of the adapter/instance to check for
      */
     private async _removeCustomFromObjects(ids: string[]): Promise<void> {
-        // get all objects which have a custom attribute
+        // get all objects that have a custom attribute
         const res = await this.objects.getObjectViewAsync('system', 'custom', {
             startkey: '',
             endkey: '\u9999'
@@ -1739,7 +1739,7 @@ export class Install {
      * @param name package name
      */
     async installAdapterFromUrl(url: string, name: string): Promise<void> {
-        // If the user provided an URL, try to parse it into known ways to represent a Github URL
+        // If the user provided a URL, try to parse it into known ways to represent a GitHub URL
         let parsedUrl;
         try {
             parsedUrl = new URL(url);
@@ -1764,7 +1764,7 @@ export class Install {
                     const result = await axios(`http://api.github.com/repos/${user}/${repo}/commits`, {
                         headers: {
                             'User-Agent': 'ioBroker Adapter install',
-                            // @ts-expect-error should be okay..
+                            // @ts-expect-error should be okay...
                             validateStatus: status => status === 200
                         }
                     });
@@ -1793,14 +1793,14 @@ export class Install {
 
         // Try to extract name from URL
         if (!name) {
-            const reNpmPacket = new RegExp('^' + tools.appName + '\\.([-_\\w\\d]+)(@.*)?$', 'i');
+            const reNpmPacket = new RegExp(`^${tools.appName}\\.([-_\\w\\d]+)(@.*)?$`, 'i');
             const match = reNpmPacket.exec(url); // we have [email protected]
             if (match) {
                 name = match[1];
             } else if (url.match(/\.(tgz|gz|zip|tar\.gz)$/)) {
                 const parts = url.split('/');
                 const last = parts.pop()!;
-                const mm = last.match(/\.([-_\w\d]+)-[.\d]+/);
+                const mm = last.match(/\.([-_\w]+)-[.\d]+/);
                 if (mm) {
                     name = mm[1];
                 }
@@ -1814,7 +1814,7 @@ export class Install {
                     name = url;
                 }
                 // Remove the leading `iobroker.` from the name
-                const reG = new RegExp(tools.appName + '\\.([-_\\w\\d]+)$', 'i');
+                const reG = new RegExp(`${tools.appName}\\.([-_\\w\\d]+)$`, 'i');
                 const match = reG.exec(name);
                 if (match) {
                     name = match[1];
@@ -1883,7 +1883,7 @@ export class Install {
      *
      * @param adapter adapter name
      * @param instance instance, like 1
-     * @returns if dependent exists returns adapter name
+     * @returns if dependent exists, returns adapter name
      */
     private async _hasDependentInstances(adapter: string, instance?: number): Promise<void | string> {
         try {
@@ -1907,7 +1907,7 @@ export class Install {
 
             for (const row of doc.rows) {
                 if (!row.value?.common) {
-                    // this object seems to be corrupted so it will not need our adapter
+                    // this object seems to be corrupted, so it will not need our adapter
                     continue;
                 }
 
@@ -1919,7 +1919,7 @@ export class Install {
                             // this adapter needs us locally and all instances should be deleted
                             return `${row.value.common.name}.${row.id.split('.').pop()}`;
                         } else {
-                            // check if other instance of us exists on this host
+                            // check if another instance of us exists on this host
                             if (this._checkDependencyFulfilledThisHost(adapter, instance, doc.rows, scopedHostname)) {
                                 // there are other instances of our adapter - ok
                                 break;
@@ -1935,7 +1935,7 @@ export class Install {
                 for (const globalDep of Object.keys(globalDeps)) {
                     if (globalDep === adapter) {
                         if (instance === undefined) {
-                            // all instances on this host should be removed so check if there are some on other hosts
+                            // all instances on this host should be removed, so check if there are some on other hosts
                             if (this._checkDependencyFulfilledForeignHosts(adapter, doc.rows, scopedHostname)) {
                                 break;
                             } else {
@@ -1964,7 +1964,7 @@ export class Install {
      * @param adapter adapter name
      * @param instancesRows all instances objects view rows
      * @param scopedHostname hostname which should be assumed as local
-     * @returns true if an instance is present on other host
+     * @returns true if an instance is present on another host
      */
     private _checkDependencyFulfilledForeignHosts(
         adapter: string,

packages/cli/src/lib/setup/setupUpgrade.ts

@@ -81,10 +81,10 @@ export class Upgrade {
 
             while (relevantAdapters.length) {
                 let oneAdapterAdded = false;
-                // create ordered list for upgrades
+                // create an ordered list for upgrades
                 for (let i = relevantAdapters.length - 1; i >= 0; i--) {
                     const relAdapter = relevantAdapters[i];
-                    // if new version has no dependencies we can upgrade
+                    // if a new version has no dependencies, we can upgrade
                     if (!repo[relAdapter].dependencies && !repo[relAdapter].globalDependencies) {
                         // no deps, simply add it
                         sortedAdapters.push(relAdapter);
@@ -101,7 +101,7 @@ export class Upgrade {
                         for (const [depName, version] of Object.entries(allDeps)) {
                             debug(`adapter "${relAdapter}" has dependency "${depName}": "${version}"`);
                             if (version !== '*') {
-                                // dependency is important, because it affects version range
+                                // dependency is important because it affects the version range
                                 if (relevantAdapters.includes(depName)) {
                                     // the dependency is also in the upgrade list and not previously added, we should add the dependency first
                                     debug(`conflict for dependency "${depName}" at adapter "${relAdapter}"`);
@@ -110,7 +110,7 @@ export class Upgrade {
                                 }
                             }
                         }
-                        // we reached here and no conflict so every dep is satisfied
+                        // we reached here and no conflict, so every dep is satisfied
                         if (!conflict) {
                             sortedAdapters.push(relAdapter);
                             relevantAdapters.splice(relevantAdapters.indexOf(relAdapter), 1);
@@ -204,7 +204,7 @@ export class Upgrade {
                         gInstances = objs.rows.filter(obj => obj.value.common && obj.value.common.name === dName);
                     }
                     if (deps[dName] !== undefined) {
-                        // local dep get all instances on same host
+                        // local dependencies: get all instances on the same host
                         locInstances = objs.rows.filter(
                             obj =>
                                 obj.value.common &&
@@ -217,7 +217,7 @@ export class Upgrade {
                     }
 
                     let isFound = false;
-                    // we check, that all instances match - respect different local and global dep versions
+                    // we check that all instances match - respect different local and global dep versions
                     for (const instance of locInstances) {
                         const instanceVersion = instance.value.common.version;
                         try {
@@ -277,9 +277,9 @@ export class Upgrade {
     }
 
     /**
-     * Try to async upgrade adapter from given source with some checks
+     * Try to async upgrade adapter from a given source with some checks
      *
-     * @param repoUrlOrObject url of the selected repository or parsed repo, if undefined use current active repository
+     * @param repoUrlOrObject url of the selected repository or parsed repo, if undefined, use current active repository
      * @param adapter name of the adapter (can also include version like [email protected])
      * @param forceDowngrade flag to force downgrade
      * @param autoConfirm automatically confirm the tty questions (bypass)
@@ -353,7 +353,7 @@ export class Upgrade {
 
         const adapterDir = tools.getAdapterDir(adapter);
 
-        // Read actual description of installed adapter with version
+        // Read the actual description of installed adapter with a version
         if (!adapterDir || (!version && !fs.existsSync(path.join(adapterDir, 'io-package.json')))) {
             return console.log(
                 `Adapter "${adapter}"${
@@ -395,7 +395,7 @@ export class Upgrade {
             const isMajor = semver.major(installedVersion) !== semver.major(targetVersion);
 
             if (autoConfirm || (!tty.isatty(process.stdout.fd) && (!isMajor || !upgradeAll))) {
-                // force flag or script on non major or single adapter upgrade -> always upgrade
+                // force flag or script on non-major or single adapter upgrade -> always upgrade
                 return true;
             }
 
@@ -512,7 +512,7 @@ export class Upgrade {
             return true;
         };
 
-        // If version is included in repository
+        // If a version is included in the repository
         if (repoAdapter.version) {
             if (!forceDowngrade) {
                 try {
@@ -604,7 +604,7 @@ export class Upgrade {
                     } is up to date.`
                 );
             } else {
-                // Get the adapter from web site
+                // Get the adapter from website
                 const targetVersion = version || ioPack.common.version;
 
                 const isIgnored = await isVersionIgnored({

packages/cli/src/lib/setup/utils.ts

@@ -12,7 +12,7 @@ interface GetRepositoryOptions {
 }
 
 /**
- * Get json of the given repository
+ * Get JSON of the given repository
  *
  * @param options Repository specific options
  */

packages/types-dev/objects.d.ts

@@ -702,6 +702,8 @@ declare global {
             platform: 'Javascript/Node.js';
             /** The keys of common attributes (e.g. `history`) which are not deleted in a `setObject` call even if they are not present. Deletion must be done explicitly by setting them to `null`. */
             preserveSettings?: string | string[];
+            /** Url of the ReadMe file */
+            readme?: string;
             /** Which adapters must be restarted after installing or updating this adapter. */
             restartAdapters?: string[];
             /** CRON schedule to restart mode `daemon` adapters */