Added support for dev-server (#760)

Co-authored-by: AlCalzone <[email protected]>

CHANGELOG.md

@@ -19,6 +19,7 @@
 * (AlCalzone) Enable TypeScript sourcemaps (#755) · [Migration guide](docs/updates/20210515_sourcemaps.md)
 * (AlCalzone) Add Node 16 to test suite, drop Node 10 (#756) · [Migration guide](docs/updates/20210515_test_node_16.md)
 * (UncleSamSwiss) Add option for release script (#759) · [Migration guide](docs/updates/20210519_release_script.md)
+* (UncleSamSwiss) Add option for dev-server (#760) · [Migration guide](docs/updates/20210519_dev_server.md)
 
 ## 1.33.0 (2021-04-05)
 * (AlCalzone) The generated `io-package.json` files are now validated with the official JSON schema during tests (#711)

docs/updates/20210519_dev_server.md

@@ -0,0 +1,13 @@
+# Support for dev-server
+
+If you wish to use `dev-server` with your adapter, please follow these steps (taken from the [official documentation](https://github.com/ioBroker/dev-server#tldr)):
+
+```bash
+npm install --global @iobroker/dev-server
+dev-server setup
+dev-server watch
+```
+
+## More information
+
+For further information, check the [official documentation](https://github.com/ioBroker/dev-server#readme).

src/cli.ts

@@ -245,6 +245,8 @@ const installDependencies = !argv.noInstall || !!argv.install;
 let needsBuildStep: boolean;
 /** Whether the initial commit should be performed automatically */
 let gitCommit: boolean;
+/** Whether dev-server should be installed */
+let devServer: boolean;
 
 /** CLI-specific functionality for creating the adapter directory */
 async function setupProject_CLI(
@@ -278,6 +280,20 @@ async function setupProject_CLI(
 		}
 	}
 
+	if (devServer) {
+		logProgress("Installing dev-server");
+		await executeCommand(
+			isWindows ? "npm.cmd" : "npm",
+			["install", "--quiet", "--global", "@iobroker/dev-server"],
+			{ cwd: targetDir },
+		);
+		await executeCommand(
+			isWindows ? "iobroker-dev-server.cmd" : "iobroker-dev-server",
+			["setup", "--adminPort", `${answers.devServerPort}`],
+			{ cwd: targetDir },
+		);
+	}
+
 	if (gitCommit) {
 		logProgress("Initializing git repo");
 		// As described here: https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/
@@ -321,6 +337,8 @@ if (process.env.TEST_STARTUP) {
 			answers.tabReact === "yes";
 		if (needsBuildStep) maxSteps++;
 	}
+	devServer = answers.devServer === "yes";
+	if (devServer) maxSteps++;
 	gitCommit = answers.gitCommit === "yes";
 	if (gitCommit) maxSteps++;
 

src/lib/core/questions.ts

@@ -655,7 +655,33 @@ export const questionGroups: QuestionGroup[] = [
 						? "yes"
 						: "no",
 			},
-
+			{
+				condition: [
+					{ name: "features", contains: "adapter" },
+					{ name: "cli", value: true },
+				],
+				type: "select",
+				name: "devServer",
+				label: "ioBroker dev-server",
+				optional: true,
+				message:
+					"Would you like to use dev-server to develop and test your code with a simple command line tool?",
+				initial: "yes",
+				choices: ["yes", "no"],
+				migrate: () => "yes",
+			},
+			{
+				condition: { name: "devServer", contains: "yes" },
+				type: "numeral",
+				name: "devServerPort",
+				label: "dev-server Admin Port",
+				message:
+					"Please choose the port number on which dev-server should present the admin web interface:",
+				initial: 8081,
+				min: 1024,
+				max: 0xffff,
+				migrate: () => 8081,
+			},
 			{
 				condition: { name: "features", contains: "adapter" },
 				type: "select",
@@ -904,6 +930,8 @@ export interface Answers {
 	adminReact?: "yes" | "no";
 	tabReact?: "yes" | "no";
 	releaseScript?: "yes" | "no";
+	devServer?: "yes" | "no";
+	devServerPort?: number;
 	indentation?: "Tab" | "Space (4)";
 	quotes?: "single" | "double";
 	es6class?: "yes" | "no";

templates/README.md.ts

@@ -17,6 +17,7 @@ export = (answers => {
 	const useTravis = answers.ci === "travis";
 	const useGithubActions = answers.ci === "gh-actions";
 	const useReleaseScript = answers.releaseScript === "yes";
+	const useDevServer = answers.devServer === "yes";
 	const useDependabot = answers.dependabot === "yes";
 
 	const npmScripts: Record<string, string> = {};
@@ -151,7 +152,19 @@ Additional command line options for the release script are explained in the
 ` : ""}To get your ${isAdapter ? "adapter" : "widget"} released in ioBroker, please refer to the documentation 
 of [ioBroker.repositories](https://github.com/ioBroker/ioBroker.repositories#requirements-for-adapter-to-get-added-to-the-latest-repository).
 
+${useDevServer ? `
+### Test the adapter manually with dev-server
+Since you set up \`dev-server\`, you can use it to run, test and debug your adapter.
 
+You may start \`dev-server\` by calling from your dev directory:
+\`\`\`bash
+dev-server watch
+\`\`\`
+
+The ioBroker.admin interface will then be available at http://localhost:${answers.devServerPort}/
+
+Please refer to the [\`dev-server\` documentation](https://github.com/ioBroker/dev-server#command-line) for more details.
+` : `
 ### Test the adapter manually on a local ioBroker installation
 In order to install the adapter locally without publishing, the following steps are recommended:
 1. Create a tarball from your dev directory:  
@@ -168,7 +181,7 @@ In order to install the adapter locally without publishing, the following steps
 For later updates, the above procedure is not necessary. Just do the following:
 1. Overwrite the changed files in the adapter directory (\`/opt/iobroker/node_modules/iobroker.${adapterNameLowerCase}\`)
 1. Execute \`iobroker upload ${adapterNameLowerCase}\` on the ioBroker host
-
+`}
 ## Changelog
 ${useReleaseScript ? `<!--
     Placeholder for the next version (at the beginning of the line):

templates/_gitignore.ts

@@ -14,6 +14,9 @@ nbproject
 # npm package files
 iobroker.*.tgz
 
+# ioBroker dev-server
+.dev-server/
+
 Thumbs.db
 ${useNyc ? `
 # NYC coverage files

test/baselines/adapter_JS_ES6Class_ESLint_TypeChecking_Spaces_SingleQuotes_Apache-2.0/.gitignore

@@ -7,6 +7,9 @@ nbproject
 # npm package files
 iobroker.*.tgz
 
+# ioBroker dev-server
+.dev-server/
+
 Thumbs.db
 
 # i18n intermediate files

test/baselines/adapter_JS_ESLint_TypeChecking_Spaces_SingleQuotes_Apache-2.0/.gitignore

@@ -7,6 +7,9 @@ nbproject
 # npm package files
 iobroker.*.tgz
 
+# ioBroker dev-server
+.dev-server/
+
 Thumbs.db
 
 # i18n intermediate files

test/baselines/adapter_JS_React/.gitignore

@@ -7,6 +7,9 @@ nbproject
 # npm package files
 iobroker.*.tgz
 
+# ioBroker dev-server
+.dev-server/
+
 Thumbs.db
 
 # i18n intermediate files

test/baselines/adapter_TS_ES6Class_ESLint_Tabs_DoubleQuotes_MIT/.gitignore

@@ -7,6 +7,9 @@ nbproject
 # npm package files
 iobroker.*.tgz
 
+# ioBroker dev-server
+.dev-server/
+
 Thumbs.db
 
 # i18n intermediate files

test/baselines/adapter_TS_ESLint_Tabs_DoubleQuotes_MIT/.gitignore

@@ -7,6 +7,9 @@ nbproject
 # npm package files
 iobroker.*.tgz
 
+# ioBroker dev-server
+.dev-server/
+
 Thumbs.db
 
 # i18n intermediate files

test/baselines/adapter_TS_React/.gitignore

@@ -7,6 +7,9 @@ nbproject
 # npm package files
 iobroker.*.tgz
 
+# ioBroker dev-server
+.dev-server/
+
 Thumbs.db
 
 # i18n intermediate files

test/baselines/dev-server/README.md

@@ -0,0 +1,120 @@
+![Logo](admin/test-adapter.png)
+# ioBroker.test-adapter
+
+[![NPM version](https://img.shields.io/npm/v/iobroker.test-adapter.svg)](https://www.npmjs.com/package/iobroker.test-adapter)
+[![Downloads](https://img.shields.io/npm/dm/iobroker.test-adapter.svg)](https://www.npmjs.com/package/iobroker.test-adapter)
+![Number of Installations (latest)](https://iobroker.live/badges/test-adapter-installed.svg)
+![Number of Installations (stable)](https://iobroker.live/badges/test-adapter-stable.svg)
+[![Dependency Status](https://img.shields.io/david/AlCalzone/iobroker.test-adapter.svg)](https://david-dm.org/AlCalzone/iobroker.test-adapter)
+
+[![NPM](https://nodei.co/npm/iobroker.test-adapter.png?downloads=true)](https://nodei.co/npm/iobroker.test-adapter/)
+
+**Tests:** ![Test and Release](https://github.com/AlCalzone/ioBroker.test-adapter/workflows/Test%20and%20Release/badge.svg)
+
+## test-adapter adapter for ioBroker
+
+Describe your project here
+
+## Developer manual
+This section is intended for the developer. It can be deleted later
+
+### Getting started
+
+You are almost done, only a few steps left:
+1. Create a new repository on GitHub with the name `ioBroker.test-adapter`
+1. Initialize the current folder as a new git repository:  
+	```bash
+	git init
+	git add .
+	git commit -m "Initial commit"
+	```
+1. Link your local repository with the one on GitHub:  
+	```bash
+	git remote add origin https://github.com/AlCalzone/ioBroker.test-adapter
+	```
+
+1. Push all files to the GitHub repo:  
+	```bash
+	git push origin master
+	```
+1. Add a new secret under https://github.com/AlCalzone/ioBroker.test-adapter/settings/secrets. It must be named `AUTO_MERGE_TOKEN` and contain a personal access token with push access to the repository, e.g. yours. You can create a new token under https://github.com/settings/tokens.
+
+1. Head over to [src/main.ts](src/main.ts) and start programming!
+
+### Best Practices
+We've collected some [best practices](https://github.com/ioBroker/ioBroker.repositories#development-and-coding-best-practices) regarding ioBroker development and coding in general. If you're new to ioBroker or Node.js, you should
+check them out. If you're already experienced, you should also take a look at them - you might learn something new :)
+
+### Scripts in `package.json`
+Several npm scripts are predefined for your convenience. You can run them using `npm run <scriptname>`
+| Script name | Description |
+|-------------|-------------|
+| `build:ts` | Compile the TypeScript sources. |
+| `watch:ts` | Compile the TypeScript sources and watch for changes. |
+| `watch` | Shortcut for `npm run watch:ts` |
+| `test:ts` | Executes the tests you defined in `*.test.ts` files. |
+| `test:package` | Ensures your `package.json` and `io-package.json` are valid. |
+| `test:unit` | Tests the adapter startup with unit tests (fast, but might require module mocks to work). |
+| `test:integration` | Tests the adapter startup with an actual instance of ioBroker. |
+| `test` | Performs a minimal test run on package files and your tests. |
+| `check` | Performs a type-check on your code (without compiling anything). |
+| `lint` | Runs `ESLint` to check your code for formatting errors and potential bugs. |
+
+### Writing tests
+When done right, testing code is invaluable, because it gives you the 
+confidence to change your code while knowing exactly if and when 
+something breaks. A good read on the topic of test-driven development 
+is https://hackernoon.com/introduction-to-test-driven-development-tdd-61a13bc92d92. 
+Although writing tests before the code might seem strange at first, but it has very 
+clear upsides.
+
+The template provides you with basic tests for the adapter startup and package files.
+It is recommended that you add your own tests into the mix.
+
+### Publishing the adapter
+Since you have chosen GitHub Actions as your CI service, you can 
+enable automatic releases on npm whenever you push a new git tag that matches the form 
+`v<major>.<minor>.<patch>`. The necessary steps are described in `.github/workflows/test-and-release.yml`.
+
+To get your adapter released in ioBroker, please refer to the documentation 
+of [ioBroker.repositories](https://github.com/ioBroker/ioBroker.repositories#requirements-for-adapter-to-get-added-to-the-latest-repository).
+
+### Test the adapter manually with dev-server
+Since you set up `dev-server`, you can use it to run, test and debug your adapter.
+
+You may start `dev-server` by calling from your dev directory:
+```bash
+dev-server watch
+```
+
+The ioBroker.admin interface will then be available at http://localhost:9003/
+
+Please refer to the [`dev-server` documentation](https://github.com/ioBroker/dev-server#command-line) for more details.
+
+## Changelog
+
+### 0.0.1
+* (Al Calzone) initial release
+
+## License
+MIT License
+
+Copyright (c) 2021 Al Calzone <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

test/baselines/vis_Widget/.gitignore

@@ -7,6 +7,9 @@ nbproject
 # npm package files
 iobroker.*.tgz
 
+# ioBroker dev-server
+.dev-server/
+
 Thumbs.db
 
 # i18n intermediate files

test/baselines/vis_Widget_Travis/.gitignore

@@ -7,6 +7,9 @@ nbproject
 # npm package files
 iobroker.*.tgz
 
+# ioBroker dev-server
+.dev-server/
+
 Thumbs.db
 
 # i18n intermediate files

test/create-adapter.test.ts

@@ -568,6 +568,19 @@ describe("adapter creation =>", () => {
 						file.name === "README.md",
 				);
 			});
+
+			it("dev-server", async () => {
+				const answers: Answers = {
+					...baseAnswers,
+					devServer: "yes",
+					devServerPort: 9003,
+				};
+				await expectSuccess(
+					"dev-server",
+					answers,
+					(file) => file.name === "README.md",
+				);
+			});
 		});
 	});
 });