@vcmap/plugin-cli 2.0.11 → 2.0.12

package/README.md

@@ -5,11 +5,13 @@
 > For documentation on version 1 compatible with VC Map v4, see [this tag](https://github.com/virtualcitySYSTEMS/map-plugin-cli/tree/v1.1.1)
 > and be sure to install using `npm i -g @vcmap/plugin-cli@^1.1.0`** 
 
-The `vcmplugin` cli helps develop and build plugins for the **VC Map**.
+The `@vcmap/plugin-cli` helps develop and build plugins for the **VC Map**.
 
 ## Features
 
 - Creating basic plugin structure
+  - from scratch
+  - from an existing plugin [@vcmap/hello-world](https://www.npmjs.com/package/@vcmap/hello-world) used as template
 - Providing plugin development server
 - Building plugins for production
 
@@ -40,14 +42,20 @@ its current major version. You can then use either the scripts defined
 by the template in your package.json `npm start`, `npm run pack` etc. or `npx`
 to execute CLI commands.
 
+All commands have (optional) cli options. Run `vcmplugin --help` or `vcmplugin help [command]` for more information.
+For `serve` and `preview` you can alternatively define a `vcs.config.js` in your plugin's root directory. 
+For more information see [here](#vcm-config-js).
+
 ### 1. Creating a new plugin
 
-To create a new plugin template, run the following within your projects root:
+To create a new plugin template, run the following:
 ```
 vcmplugin create
 ```
-This will open a command prompt helping you to create the basic [structure of a plugin](https://github.com/virtualcitySYSTEMS/map-plugin-examples/blob/main/doc/VCM_Plugin.md#2-structure-of-a-plugin).
-Be sure to check out the [peer dependecy section](#about_peer_dependencies) as well.
+This will open a command prompt helping you to create the basic [structure of a plugin](#vc-map-plugins).
+Be sure to check out the [peer dependecy section](#about-peer-dependencies) as well.
+
+Optionally, in step 7 of the create-prompt you can choose an existing plugin [@vcmap/hello-world](https://www.npmjs.com/package/@vcmap/hello-world) as template.
 
 ### 2. Serving a plugin for development
 
@@ -56,7 +64,7 @@ To serve your plugin in dev mode, run the following within your projects root:
 npx vcmplugin serve
 ```
 The dev mode gives you complete debug information on all integrated libraries (@vcmap/core, ol etc.)
-By default this command will launch a dev server at localhost:8008 using 
+By default, this command will launch a dev server at localhost:8008 using 
 the @vcmap/ui peer dependency package of your plugin as its base.
 You can provide an alternate map config if you wish.
 
@@ -122,15 +130,48 @@ npx vcmplugin pack
 This will create a folder `dist` with a zip file containing your bundled code and assets.
 To use the plugin productively in a hosted map, 
 unzip this file on your server to `{vcm-root}/plugins` and add 
-an entry to your VC MAP [config](#2-config) plugins section. This zip file can also be unzipped
+an entry to your VC MAP `config` plugins section. This zip file can also be unzipped
 in the VC Publishers `plugins` public directory.
 
+## vcm config js
+
+The `@vcmap/plugin-cli` supports an optional configuration file, which can be used for the commands `serve` and `preview`.
+It's an alternative to providing cli parameters (which will still have precedence) and even has a few extra feature like proxy.
+This can be helpful, if you want to share specific parameters valid for a specific plugin.
+In order to do so just save a `vcm.config.js` in your plugin's root directory.
+This file has to return a js object as default export.
+
+Example `vcm.config.js` defining proxy and port:
+```js
+export default {
+  // server.proxy see https://vitejs.dev/config/server-options.html#server-proxy
+  proxy: {
+    // string shorthand: http://localhost:8008/foo -> https://vc.systems/foo
+    '/foo': 'https://vc.systems',
+  },
+  port: 5005,
+}
+```
+
+The following parameters are valid:
+
+| parameter | type    | description                                                                                   |
+|-----------|---------|-----------------------------------------------------------------------------------------------|
+| config    | string  | an optional fileName to use for configuring the plugin                                        |
+| port      | number  | optional alternative port (default 8008)                                                      |
+| https     | boolean | wether to use http (default) or https                                                         |
+| mapConfig | string  | a filename or URL to a map config (for `serve` command)                                       |
+| vcm       | string  | a filename or URL to a map (for `preview` command)                                            |
+| proxy     | Object  | a server proxy (see [vitejs.dev](https://vitejs.dev/config/server-options.html#server-proxy)) |
+
+
 ## About Peer Dependencies
-The @vcmap/ui uses some _very large libraries_, notably `CesiumJS`. To reduce the amount
+The [@vcmap/ui](https://github.com/virtualcitySYSTEMS/map-ui) uses some _very large libraries_, notably `CesiumJS`. To reduce the amount
 of traffic generated for loading plugins, all large libraries (see the list below), 
-are _provided_ in production (instead of bundling them into every plugin). This a) guarantees
-a certain amount of type safety (using the @vcsuite/check parameter assertation library for instance),
-b) reduces the amount of traffic required to load an application and c) leverages browser
+are _provided_ in production (instead of bundling them into every plugin). This 
+a) guarantees a certain amount of type safety (using the [@vcsuite/check](https://www.npmjs.com/package/@vcsuite/check) parameter assertion library for instance),
+b) reduces the amount of traffic required to load an application and
+c) leverages browser
 caching more readily.
 
 The following libraries are provided by the @vcmap/ui in a deployed application. You should define these
@@ -141,7 +182,14 @@ as peer dependencies if you use them in your plugin:
 - vue
 - vuetify
 
-During the build step, these libraries are automatically externalized by the vcmplugin-cli and in
+If you want to update your plugin to a newer version of `@vcmap/ui`, the `@vcmap/plugin-cli` provides a update tool.
+Just change to your plugin's directory and run:
+```bash
+vcmplugin update
+```
+This will automatically update all peer dependencies defined in your plugin to the corresponding version of the latest `@vcmap/ui`.
+
+During the build step, these libraries are automatically externalized by the `@vcmap/plugin-cli` and in
 production all plugins & the map core _share_ the same cesium library.
 
 But, to make this work, it is important to define these dependencies as _peer dependencies_ of
@@ -161,7 +209,7 @@ import { Cartesian3 } from '@vcmap/cesium';
 openlayers provides a special case, since its modules do not provide a _flat_ namespace.
 To circumvent this limitation, _the @vcmap/ui provides a flat namespaced ol.js_ and a mechanic
 to rewrite openlayers imports. This is automatically applied by the `@vcmap/rollup-plugin-vcs-ol`
-used by the vcmplugin-cli build step. So openlayers imports can be written as:
+used by the `@vcmap/plugin-cli` build step. So openlayers imports can be written as:
 ```js
 import Feature from 'ol/Feature.js';
 ```
@@ -192,7 +240,7 @@ to create your project, a template already adhering to these specs will be creat
 - Plugin dependencies have to be defined in the `package.json`.
     - `dependency`: all plugin specific dependencies NOT provided by the `@vcmap/ui`.
     - `peerDependency`: dependencies provided by the `@vcmap/ui`, 
-    - e.g. `@vcmap/core` or `@vcmap/ui` (see [About Peer Dependencies](#About-Peer-Dependencies) for more details)
+      - e.g. `@vcmap/core` or `@vcmap/ui` (see [About Peer Dependencies](#About-Peer-Dependencies) for more details)
     - `devDependency`: all dependencies only required for development, e.g. `eslint`.
 - Plugins can be published to NPM, but should contain both source and minified code 
 to allow seamless integration into the [VC Map UI](https://github.com/virtualcitySYSTEMS/map-ui) environment.
@@ -305,7 +353,15 @@ cannot handle css resources.
 If you have to access assets _before_ your plugin is created (in the exported function of
 your plugin code), you will have to use the `baseUrl` provided to you to generate the URL yourself.
 
+## About testing plugins
+
+To test your plugin's API you can use [vitest](https://vitest.dev/).
+The `@vcmap/hello-world` plugin contains a basic setup of a test environment including example spec using vitest. 
+You will find the required setup in your created plugin, if you chose to add `test` as script to your `package.json` during the create-prompt.
+
+As for now, we don't do any components testing.
+
 ## Notes on Developing
 To develop the plugin-cli, be sure to not `npm link` into plugins, since this will
 throw the resolver in resolving the @vcmap/ui peer dependency from the current plugin. 
-Instead run `npm pack` in the plugin cli and install the tarball in the plugin directly.
+Instead, run `npm pack` in the plugin cli and install the tarball in the plugin directly.

package/assets/{helloWorld/.gitlab-ci.yml → .gitlab-ci.yml}

@@ -51,6 +51,16 @@ lint:
   script:
     - npm run lint
 
+test:
+  <<: *after_build_definition
+  stage: test
+  script:
+    - npm run coverage -- --reporter junit --outputFile test-report.xml
+  coverage: '/^Statements\s*:\s*([^%]+)/'
+  artifacts:
+    reports:
+      junit: test-report.xml
+
 audit:
   <<: *after_build_definition
   stage: test

package/assets/gitignore

@@ -0,0 +1,30 @@
+node_modules
+/dist
+test-report.xml
+
+
+# local env files
+.env.local
+.env.*.local
+
+# Log files
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# test output
+.nyc_output
+coverage
+
+# static output
+docs

package/assets/index.html

@@ -1,33 +1,29 @@
 <!DOCTYPE html>
 <html class="vcs-ui" lang="en">
-  <head>
+<head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width,initial-scale=1.0" />
-    <link
-      rel="stylesheet"
-      href="https://fonts.googleapis.com/css?family=Titillium+Web"
-    />
-  </head>
-  <body style="height: 100vH;">
-    <noscript>
-      <strong>...</strong>
-    </noscript>
-    <div id="app">
-      <div id="loading-wrapper">
+</head>
+<body style="height: 100vH;">
+<noscript>
+    <strong>...</strong>
+</noscript>
+<div id="app">
+    <div id="loading-wrapper">
         <div id="loading-text">LOADING</div>
         <div id="loading-content"></div>
-      </div>
     </div>
-    <style>
-      #loading-wrapper {
+</div>
+<style>
+    #loading-wrapper {
         position: fixed;
         width: 100%;
         height: 100%;
         left: 0;
         top: 0;
-      }
+    }
 
-      #loading-text {
+    #loading-text {
         display: block;
         position: absolute;
         top: 50%;
@@ -39,9 +35,9 @@
         text-align: center;
         font-family: 'PT Sans Narrow', sans-serif;
         font-size: 20px;
-      }
+    }
 
-      #loading-content {
+    #loading-content {
         display: block;
         position: relative;
         left: 50%;
@@ -49,9 +45,9 @@
         width: 170px;
         height: 170px;
         margin: -85px 0 0 -85px;
-      }
+    }
 
-      #loading-content {
+    #loading-content {
         border: 3px solid transparent;
         border-top-color: #409d76;
         border-bottom-color: #409d76;
@@ -60,22 +56,22 @@
         -moz-animation: loader 2s linear infinite;
         -o-animation: loader 2s linear infinite;
         animation: loader 2s linear infinite;
-      }
+    }
 
-      @keyframes loader {
+    @keyframes loader {
         0% {
-          -webkit-transform: rotate(0deg);
-          -ms-transform: rotate(0deg);
-          transform: rotate(0deg);
+            -webkit-transform: rotate(0deg);
+            -ms-transform: rotate(0deg);
+            transform: rotate(0deg);
         }
 
         100% {
-          -webkit-transform: rotate(360deg);
-          -ms-transform: rotate(360deg);
-          transform: rotate(360deg);
+            -webkit-transform: rotate(360deg);
+            -ms-transform: rotate(360deg);
+            transform: rotate(360deg);
         }
-      }
-    </style>
-    <script type="module" src="./node_modules/@vcmap/ui/start.js"></script>
-  </body>
+    }
+</style>
+<script type="module" src="./node_modules/@vcmap/ui/start.js"></script>
+</body>
 </html>

package/assets/index.js

@@ -0,0 +1,62 @@
+import { version, name } from '../package.json';
+
+/**
+ * @typedef {Object} PluginState
+ * @property {any} prop
+ */
+
+/**
+ * @param {T} config - the configuration of this plugin instance, passed in from the app.
+ * @param {string} baseUrl - the absolute URL from which the plugin was loaded (without filename, ending on /)
+ * @returns {import("@vcmap/ui/src/vcsUiApp").VcsPlugin<T, PluginState>}
+ * @template {Object} T
+ */
+export default function plugin(config, baseUrl) {
+  // eslint-disable-next-line no-console
+  console.log(config, baseUrl);
+  return {
+    get name() { return name; },
+    get version() { return version; },
+    /**
+     * @param {import("@vcmap/ui").VcsUiApp} vcsUiApp
+     * @param {PluginState=} state
+     * @returns {Promise<void>}
+     */
+    initialize: async (vcsUiApp, state) => {
+      // eslint-disable-next-line no-console
+      console.log('Called before loading the rest of the current context. Passed in the containing Vcs UI App ', vcsUiApp, state);
+    },
+    /**
+     * @param {import("@vcmap/ui").VcsUiApp} vcsUiApp
+     * @returns {Promise<void>}
+     */
+    onVcsAppMounted: async (vcsUiApp) => {
+      // eslint-disable-next-line no-console
+      console.log('Called when the root UI component is mounted and managers are ready to accept components', vcsUiApp);
+    },
+    /**
+     * @returns {T}
+     */
+    toJSON() {
+      // eslint-disable-next-line no-console
+      console.log('Called when serializing this plugin instance');
+      return {};
+    },
+    /**
+     * should return the plugins state
+     * @param {boolean} forUrl
+     * @returns {PluginState}
+     */
+    getState(forUrl) {
+      // eslint-disable-next-line no-console
+      console.log('Called when collecting state, e.g. for create link', forUrl);
+      return {
+        prop: '*',
+      };
+    },
+    destroy() {
+      // eslint-disable-next-line no-console
+      console.log('hook to cleanup');
+    },
+  };
+}

package/cli.js

@@ -2,9 +2,9 @@
 import program from 'commander';
 import './src/defaultCommand.js';
 import {
-  create, serve, build, pack, preview,
+  create, serve, build, pack, preview, update,
 } from './index.js';
-import { version } from './src/create.js';
+import { version } from './src/pluginCliHelper.js';
 import setupMapUi from './src/setupMapUi.js';
 import buildStagingApp from './src/buildStagingApp.js';
 
@@ -25,13 +25,6 @@ program
   .defaultOptions()
   .defaultServeOptions()
   .option('--vcm [url]', 'URL to a virtualcityMAP application', val => val.replace(/\/$/, ''))
-  .option('--proxyRoute <route>', 'a route to proxy as well (e.g. if you have additional proxies on your server)', (val, prev) => {
-    if (!prev) {
-      return [val];
-    }
-    prev.push(val);
-    return prev;
-  }, [])
   .safeAction(preview);
 
 program
@@ -57,4 +50,9 @@ program
   .command('setup-map-ui')
   .safeAction(setupMapUi);
 
+program
+  .command('update')
+  .defaultOptions()
+  .safeAction(update);
+
 program.parse(process.argv);

package/index.js

@@ -4,5 +4,6 @@ export { default as build } from './src/build.js';
 export { default as pack } from './src/pack.js';
 export { default as preview } from './src/preview.js';
 export { default as buildStagingApp } from './src/buildStagingApp.js';
+export { default as update } from './src/update.js';
 export { default as setupMapUi } from './src/setupMapUi.js';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vcmap/plugin-cli",
-  "version": "2.0.11",
+  "version": "2.0.12",
   "description": "A CLI to help develop and build plugins for the VC Map",
   "main": "index.js",
   "type": "module",
@@ -34,13 +34,14 @@
     "prompts": "^2.4.1",
     "sass": "1.32.13",
     "semver": "^7.3.5",
+    "tar": "^6.1.13",
     "vite": "^3.2.0",
     "vite-plugin-vue2": "^2.0.2",
-    "vue-template-compiler": "~2.7.3"
+    "vue-template-compiler": "~2.7.14"
   },
   "peerDependencies": {
     "@vcmap/ui": "^5.0.0-rc.15",
-    "vue": "~2.7.3"
+    "vue": "~2.7.14"
   },
   "peerDependenciesMeta": {
     "@vcmap/ui": {

package/src/buildStagingApp.js

@@ -1,8 +1,9 @@
 import { cp, copyFile, writeFile, rm, mkdir } from 'fs/promises';
 import path from 'path';
 import fs from 'fs';
+import { logger } from '@vcsuite/cli-logger';
 import { getContext, resolveContext } from './context.js';
-import { getConfigJson } from './hostingHelpers.js';
+import { executeUiNpm, getConfigJson, resolveMapUi } from './hostingHelpers.js';
 import { getPluginName } from './packageJsonHelpers.js';
 import buildModule, { getDefaultConfig } from './build.js';
 import setupMapUi from './setupMapUi.js';
@@ -34,6 +35,15 @@ export default async function buildStagingApp() {
     );
   }
 
+  // In case @vcmap/ui is linked via git+ssh, dist folder is not available and must be built first
+  if (!fs.existsSync(resolveMapUi('dist'))) {
+    logger.spin('building @vcmap/ui');
+    await executeUiNpm('--production=false --no-package-lock', 'install');
+    await executeUiNpm('build');
+    logger.stopSpinner();
+    logger.info('@vcmap/ui built');
+  }
+
   await copyFile(
     path.join(getContext(), 'node_modules', '@vcmap', 'ui', 'dist', 'index.html'),
     path.join(distPath, 'index.html'),
@@ -55,4 +65,5 @@ export default async function buildStagingApp() {
     path.join(distPath, 'config'),
     { recursive: true },
   );
+  logger.success('buildStagingApp finished');
 }

package/src/create.js

@@ -2,14 +2,12 @@ import fs from 'fs';
 import path from 'path';
 import prompts from 'prompts';
 import semver from 'semver';
-import util from 'util';
-import childProcess from 'child_process';
+import tar from 'tar';
 import { logger } from '@vcsuite/cli-logger';
 import { LicenseType, writeLicense } from './licenses.js';
-import { getDirname } from './hostingHelpers.js';
-
-export const { version, name } = JSON.parse(fs.readFileSync(path.join(getDirname(), '..', 'package.json')).toString());
-const exec = util.promisify(childProcess.exec);
+import { DepType, installDeps } from './packageJsonHelpers.js';
+import { updatePeerDependencies } from './update.js';
+import { name, version, promiseExec, getDirname } from './pluginCliHelper.js';
 
 /**
  * @typedef {Object} PluginTemplateOptions
@@ -20,77 +18,120 @@ const exec = util.promisify(childProcess.exec);
  * @property {string} author
  * @property {string} repository
  * @property {string} license
+ * @property {string} template
  * @property {Array<string>} peerDeps
+ * @property {boolean} gitlabCi
  */
 
 /**
- * @enum {number}
- */
-const DepType = {
-  DEP: 1,
-  PEER: 2,
-  DEV: 3,
-};
-
-/**
- * @param {Array<string>} deps
- * @param {DepType} type
+ * @param {string} pluginName
  * @param {string} pluginPath
- * @returns {Promise<void>}
+ * @param {string[]} filter - files or dirs to be extracted
  */
-async function installDeps(deps, type, pluginPath) {
-  let save = '--save';
-  if (type === DepType.PEER) {
-    save = '--save-peer';
-  } else if (type === DepType.DEV) {
-    save = '--save-dev';
+async function downloadAndExtractPluginTar(pluginName, pluginPath, filter = undefined) {
+  const logMsg = filter ? filter.join(', ') : pluginName;
+  logger.spin(`Downloading and extracting ${logMsg}`);
+  const { stdout: packOut, stderr: packErr } = await promiseExec(`npm pack ${pluginName} --quiet`, { cwd: pluginPath });
+  logger.error(packErr);
+
+  const tarName = packOut.trim();
+  const tarPath = path.join(pluginPath, tarName);
+  const extractOptions = {
+    file: tarPath,
+    cwd: pluginPath,
+    strip: 1,
+  };
+  if (filter) {
+    extractOptions.filter = entryPath => filter.some(f => entryPath.includes(f));
   }
-  const installCmd = `npm i ${save} ${deps.join(' ')}`;
-  const { stdout, stderr } = await exec(installCmd, { cwd: pluginPath });
-  logger.log(stdout);
-  logger.error(stderr);
+  await tar.x(extractOptions);
+  await fs.promises.rm(tarPath);
+  logger.success(`Downloaded and extracted template ${logMsg}`);
+  logger.stopSpinner();
 }
 
 /**
- * @param {Array<string>} deps
+ * Copies an existing plugin as template and edits package.json
+ * @param {PluginTemplateOptions} options
  * @param {string} pluginPath
  * @returns {Promise<void>}
  */
-async function setUiPeerDepVersions(deps, pluginPath) {
-  const uiPackageJsonContent = await fs.promises.readFile(
-    path.join(pluginPath, 'node_modules', '@vcmap', 'ui', 'package.json'),
+async function copyPluginTemplate(options, pluginPath) {
+  await downloadAndExtractPluginTar(options.template, pluginPath);
+
+  const pluginPackageJson = JSON.parse((await fs.promises.readFile(path.join(pluginPath, 'package.json'))).toString());
+  const userPackageJson = {
+    name: options.name,
+    version: options.version,
+    description: options.description,
+    author: options.author,
+    license: options.license,
+  };
+  const packageJson = { ...pluginPackageJson, ...userPackageJson };
+  if (options.repository) {
+    packageJson.repository = {
+      url: options.repository,
+    };
+  } else {
+    delete options.repository;
+  }
+
+  const writePackagePromise = fs.promises.writeFile(
+    path.join(pluginPath, 'package.json'),
+    JSON.stringify(packageJson, null, 2),
   );
-  const uiPackageJson = JSON.parse(uiPackageJsonContent);
-  deps.forEach((dep, index) => {
-    if (uiPackageJson.peerDependencies[dep]) {
-      deps[index] = `${dep}@${uiPackageJson.peerDependencies[dep]}`;
+
+  const configJson = JSON.parse((await fs.promises.readFile(path.join(pluginPath, 'config.json'))).toString());
+  configJson.name = options.name;
+
+  const writeConfigPromise = fs.promises.writeFile(
+    path.join(pluginPath, 'config.json'),
+    JSON.stringify(configJson, null, 2),
+  );
+
+  await Promise.all([
+    writePackagePromise,
+    writeConfigPromise,
+  ]);
+  logger.debug('created plugin template');
+
+  try {
+    await updatePeerDependencies(packageJson.peerDependencies, pluginPath);
+    logger.spin('installing dependencies... (this may take a while)');
+    if (packageJson.dependencies) {
+      const deps = Object.entries(packageJson.dependencies)
+        .map(([depName, depVersion]) => `${depName}@${depVersion}`);
+      await installDeps(deps, DepType.DEP, pluginPath);
     }
-  });
+    await installDeps([`${name}@${version}`], DepType.DEV, pluginPath);
+    logger.success('Installed dependencies');
+  } catch (e) {
+    logger.error(e);
+    logger.failure('Failed installing dependencies');
+  }
+  logger.stopSpinner();
 }
 
 /**
+ * Creates a plugin from scratch
  * @param {PluginTemplateOptions} options
+ * @param {string} pluginPath
  */
-async function createPluginTemplate(options) {
-  if (!options.name) {
-    logger.error('please provide a plugin name as input parameter');
-    process.exit(1);
+async function createPluginTemplate(options, pluginPath) {
+  const installVitest = options.scripts && options.scripts.find(script => script.test);
+  if (!installVitest) {
+    options.scripts.push({ test: 'echo "Error: no test specified" && exit 1' });
+  } else {
+    options.scripts.push(
+      { coverage: 'vitest run --coverage' },
+    );
   }
-  logger.info(`creating new plugin: ${options.name}`);
 
-  const pluginPath = path.join(process.cwd(), options.name);
-  if (fs.existsSync(pluginPath)) {
-    logger.error('plugin with the provided name already exists');
-    process.exit(1);
-  }
-
-  await fs.promises.mkdir(pluginPath);
-  await fs.promises.mkdir(path.join(pluginPath, 'plugin-assets'));
-  logger.debug('created plugin directory');
   const packageJson = {
     name: options.name,
     version: options.version,
     description: options.description,
+    type: 'module',
     main: 'src/index.js',
     scripts: Object.assign({ prepublishOnly: 'vcmplugin build' }, ...options.scripts),
     author: options.author,
@@ -142,6 +183,66 @@ async function createPluginTemplate(options) {
     JSON.stringify(configJson, null, 2),
   );
 
+  await fs.promises.mkdir(path.join(pluginPath, 'src'));
+  logger.debug('created src directory');
+
+  const copyIndexPromise = fs.promises.copyFile(
+    path.join(getDirname(), '..', 'assets', 'index.js'),
+    path.join(pluginPath, 'src', 'index.js'),
+  );
+
+  await Promise.all([
+    writePackagePromise,
+    writeConfigPromise,
+    copyIndexPromise,
+  ]);
+
+  if (installVitest) {
+    logger.debug('setting up test environment');
+    await downloadAndExtractPluginTar('@vcmap/hello-world', pluginPath, ['tests', 'vitest.config.js']);
+  }
+
+  try {
+    const peerDependencies = options.peerDeps.reduce((obj, key) => ({ ...obj, [key]: 'latest' }), {});
+    await updatePeerDependencies(peerDependencies, pluginPath);
+    logger.spin('installing dependencies... (this may take a while)');
+    const devDeps = [`${name}@${version}`];
+    if (installEsLint) {
+      devDeps.push('@vcsuite/eslint-config');
+    }
+    if (installVitest) {
+      devDeps.push('vite', 'vitest', '@vitest/coverage-c8', 'jest-canvas-mock', 'jsdom');
+    }
+    await installDeps(devDeps, DepType.DEV, pluginPath);
+    logger.success('Installed dependencies');
+  } catch (e) {
+    logger.error(e);
+    logger.failure('Failed installing dependencies');
+  }
+  logger.stopSpinner();
+}
+
+/**
+ * Creates a new plugin either by copying a template or from scratch
+ * @param {PluginTemplateOptions} options
+ */
+async function createPlugin(options) {
+  if (!options.name) {
+    logger.error('please provide a plugin name as input parameter');
+    process.exit(1);
+  }
+  logger.debug(`creating new plugin: ${options.name}`);
+
+  const pluginPath = path.join(process.cwd(), options.name);
+  if (fs.existsSync(pluginPath)) {
+    logger.error('plugin with the provided name already exists');
+    process.exit(1);
+  }
+
+  await fs.promises.mkdir(pluginPath);
+  await fs.promises.mkdir(path.join(pluginPath, 'plugin-assets'));
+  logger.debug('created plugin directory');
+
   const writeNpmrcPromise = fs.promises.writeFile(
     path.join(pluginPath, '.npmrc'),
     'registry=https://registry.npmjs.org\n',
@@ -160,49 +261,44 @@ async function createPluginTemplate(options) {
     `# v${options.version}\nDocument features and fixes`,
   );
 
-  await fs.promises.mkdir(path.join(pluginPath, 'src'));
-  logger.debug('created src directory');
-
-  const copyTemplatePromise = fs.promises.cp(
-    path.join(getDirname(), '..', 'assets', 'helloWorld'),
-    pluginPath,
-    { recursive: true },
+  const copyGitIgnorePromise = fs.promises.copyFile(
+    path.join(getDirname(), '..', 'assets', 'gitignore'),
+    path.join(pluginPath, '.gitignore'),
   );
 
   await Promise.all([
-    writePackagePromise,
-    writeConfigPromise,
     writeNpmrcPromise,
     writeReadmePromise,
     writeChangesPromise,
-    copyTemplatePromise,
     writeLicense(options.author, options.license, pluginPath),
+    copyGitIgnorePromise,
   ]);
 
+  if (options.gitlabCi) {
+    await fs.promises.copyFile(
+      path.join(getDirname(), '..', 'assets', '.gitlab-ci.yml'),
+      path.join(pluginPath, '.gitlab-ci.yml'),
+    );
+  }
 
-  logger.spin('installing dependencies... (this may take a while)');
-  try {
-    await installDeps(['@vcmap/ui'], DepType.PEER, pluginPath);
-    await setUiPeerDepVersions(options.peerDeps, pluginPath);
-    await installDeps(options.peerDeps, DepType.PEER, pluginPath);
-    const devDeps = [`${name}@${version}`];
-    if (installEsLint) {
-      devDeps.push('@vcsuite/eslint-config');
-    }
-    await installDeps(devDeps, DepType.DEV, pluginPath);
-    logger.success('installed dependencies');
-  } catch (e) {
-    logger.error(e);
-    logger.failure('installed dependencies');
+  if (options.template) {
+    await copyPluginTemplate(options, pluginPath);
+  } else {
+    await createPluginTemplate(options, pluginPath);
   }
-  logger.stopSpinner();
-  logger.success('created plugin');
+  logger.success(`Created plugin ${options.name}`);
 }
 
 /**
  * @returns {Promise<void>}
  */
 export default async function create() {
+  const templateChoices = [
+    { title: 'no template (basic structure)', value: null },
+    { title: 'hello-world', value: '@vcmap/hello-world' },
+    // to add further templates add a choice here
+  ];
+
   const scriptChoices = [
     { title: 'build', value: { build: 'vcmplugin build' }, selected: true },
     { title: 'pack', value: { pack: 'vcmplugin pack' }, selected: true },
@@ -210,6 +306,7 @@ export default async function create() {
     { title: 'preview', value: { preview: 'vcmplugin preview' }, selected: true },
     { title: 'buildStagingApp', value: { buildStagingApp: 'vcmplugin buildStagingApp' }, selected: true },
     { title: 'lint', value: { lint: 'eslint "{src,tests}/**/*.{js,vue}"' }, selected: true },
+    { title: 'test', value: { test: 'vitest' }, selected: true },
   ];
 
   const peerDependencyChoices = [
@@ -229,7 +326,6 @@ export default async function create() {
         if (!value) {
           return false;
         }
-
         if (fs.existsSync(path.join(process.cwd(), value))) {
           return `Directory ${value} already exists`;
         }
@@ -249,13 +345,6 @@ export default async function create() {
       message: 'Description',
       initial: '',
     },
-    {
-      type: 'multiselect',
-      message: 'Add the following scripts to the package.json.',
-      name: 'scripts',
-      choices: scriptChoices,
-      hint: '- Space to select. Enter to submit',
-    },
     {
       type: 'text',
       name: 'author',
@@ -280,15 +369,37 @@ export default async function create() {
         })),
     },
     {
+      type: 'select',
+      name: 'template',
+      message: 'Choose an existing plugin as template',
+      initial: 0,
+      choices: templateChoices,
+    },
+    {
+      type: (prev, values) => (!values.template ? 'multiselect' : null),
+      message: 'Add the following scripts to the package.json.',
+      name: 'scripts',
+      choices: scriptChoices,
+      hint: '- Space to select. Enter to submit',
+    },
+    {
+      type: (prev, values) => (!values.template ? 'multiselect' : null),
       name: 'peerDeps',
-      type: 'multiselect',
       message: 'Add the following peer dependencies to the package.json.',
       choices: peerDependencyChoices,
       hint: '- Space to select. Enter to submit',
     },
+    {
+      type: 'toggle',
+      name: 'gitlabCi',
+      message: 'Add gitlab-ci.yml?',
+      initial: false,
+      active: 'yes',
+      inactive: 'no',
+    },
   ];
 
   const answers = await prompts(questions, { onCancel() { process.exit(0); } });
 
-  await createPluginTemplate(answers);
+  await createPlugin(answers);
 }

package/src/hostingHelpers.js

@@ -1,6 +1,4 @@
-import { fileURLToPath, URL } from 'url';
-import { promisify } from 'util';
-import { exec } from 'child_process';
+import { URL } from 'url';
 import https from 'https';
 import http from 'http';
 import fs from 'fs';
@@ -8,6 +6,7 @@ import path from 'path';
 import { logger } from '@vcsuite/cli-logger';
 import { getContext, resolveContext } from './context.js';
 import { getPluginEntry, getPluginName } from './packageJsonHelpers.js';
+import { promiseExec, getDirname } from './pluginCliHelper.js';
 
 /**
  * @typedef {Object} HostingOptions
@@ -17,11 +16,6 @@ import { getPluginEntry, getPluginName } from './packageJsonHelpers.js';
  * @property {boolean} [https]
  */
 
-/**
- * @type {(arg1: string, opt?: Object) => Promise<string>}
- */
-const promiseExec = promisify(exec);
-
 /**
  * @param {...string} pathSegments
  * @returns {string}
@@ -39,13 +33,6 @@ export function checkReservedDirectories() {
     });
 }
 
-/**
- * @returns {string}
- */
-export function getDirname() {
-  return path.dirname(fileURLToPath(import.meta.url));
-}
-
 /**
  * @param {string} stringUrl
  * @param {string} auth
@@ -301,10 +288,14 @@ export function addIndexRoute(app, server, production, hostedVcm, auth) {
 }
 
 /**
- * @param {string} command
+ * @param {string|null} args
+ * @param {string} [command='run']
  * @returns {Promise<string>}
  */
-export function executeUiNpm(command) {
+export function executeUiNpm(args, command = 'run') {
   const mapUiDir = resolveMapUi();
-  return promiseExec(`npm run ${command}`, { cwd: mapUiDir });
+  if (args) {
+    return promiseExec(`npm ${command} ${args}`, { cwd: mapUiDir });
+  }
+  return promiseExec(`npm ${command}`, { cwd: mapUiDir });
 }

package/src/packageJsonHelpers.js

@@ -1,5 +1,7 @@
 import fs from 'fs';
+import { logger } from '@vcsuite/cli-logger';
 import { resolveContext } from './context.js';
+import { promiseExec } from './pluginCliHelper.js';
 
 /** @type {Object|null} */
 let packageJson = null;
@@ -7,7 +9,7 @@ let packageJson = null;
 /**
  * @returns {Promise<Object>}
  */
-async function getPackageJson() {
+export async function getPackageJson() {
   if (!packageJson) {
     const packageJsonFileName = resolveContext('package.json');
     if (!fs.existsSync(packageJsonFileName)) {
@@ -46,3 +48,34 @@ export async function getPluginEntry() {
   return entry;
 }
 
+/**
+ * @enum {number}
+ */
+export const DepType = {
+  DEP: 1,
+  PEER: 2,
+  DEV: 3,
+};
+
+/**
+ * @param {Array<string>} deps
+ * @param {DepType} type
+ * @param {string} pluginPath
+ * @returns {Promise<void>}
+ */
+export async function installDeps(deps, type, pluginPath) {
+  if (deps.length < 1) {
+    return;
+  }
+  let save = '--save';
+  if (type === DepType.PEER) {
+    save = '--save-peer';
+  } else if (type === DepType.DEV) {
+    save = '--save-dev';
+  }
+  const installCmd = `npm i ${save} ${deps.join(' ')}`;
+  logger.debug(installCmd);
+  const { stdout, stderr } = await promiseExec(installCmd, { cwd: pluginPath });
+  logger.log(stdout);
+  logger.error(stderr);
+}

package/src/pluginCliHelper.js

@@ -0,0 +1,41 @@
+import fs from 'fs';
+import path from 'path';
+import util from 'util';
+import childProcess from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { logger } from '@vcsuite/cli-logger';
+import { getContext } from './context.js';
+
+/**
+ * @returns {string}
+ */
+export function getDirname() {
+  return path.dirname(fileURLToPath(import.meta.url));
+}
+
+/**
+ * @type {string} version
+ * @type {string} name
+ */
+export const { version, name } = JSON.parse(fs.readFileSync(path.join(getDirname(), '..', 'package.json')).toString());
+
+/**
+ * @type {(arg1: string) => Promise<string>}
+ */
+export const promiseExec = util.promisify(childProcess.exec);
+
+export async function getVcmConfigJs() {
+  let vcmConfigJs = {};
+  const vcmConfigJsPath = path.resolve(getContext(), 'vcm.config.js');
+  if (!fs.existsSync(vcmConfigJsPath)) {
+    logger.debug(`${vcmConfigJsPath} not existing!`);
+    return vcmConfigJs;
+  }
+  try {
+    vcmConfigJs = await import(pathToFileURL(vcmConfigJsPath));
+    logger.info('Using vcm.config.js found in current project.');
+  } catch (err) {
+    logger.error(err);
+  }
+  return vcmConfigJs;
+}

package/src/preview.js

@@ -10,11 +10,13 @@ import {
   addPluginAssets,
   checkReservedDirectories,
   createConfigJsonReloadPlugin,
-  printVcmapUiVersion, resolveMapUi,
+  printVcmapUiVersion,
+  resolveMapUi,
 } from './hostingHelpers.js';
 import build, { getDefaultConfig, getLibraryPaths } from './build.js';
 import { getContext } from './context.js';
 import setupMapUi from './setupMapUi.js';
+import { getVcmConfigJs } from './pluginCliHelper.js';
 
 /**
  * @typedef {HostingOptions} PreviewOptions
@@ -61,7 +63,7 @@ async function getServerOptions(hostedVcm, https) {
       alias,
     },
     server: {
-      middlewareMode: 'html',
+      middlewareMode: true,
       proxy,
       https,
     },
@@ -73,20 +75,22 @@ async function getServerOptions(hostedVcm, https) {
  * @returns {Promise<void>}
  */
 export default async function preview(options) {
-  if (!options.vcm) {
+  const { default: vcmConfigJs } = await getVcmConfigJs();
+  const mergedOptions = { ...vcmConfigJs, ...options };
+  if (!mergedOptions.vcm) {
     await printVcmapUiVersion();
   }
   checkReservedDirectories();
   await build({ development: false, watch: true });
   const app = express();
   logger.info('Starting preview server...');
-  const server = await createServer(await getServerOptions(options.vcm, options.https));
+  const server = await createServer(await getServerOptions(mergedOptions.vcm, mergedOptions.https));
 
-  addMapConfigRoute(app, options.vcm ? `${options.vcm}/map.config.json` : null, options.auth, options.config, true);
-  addIndexRoute(app, server, true, options.vcm, options.auth);
+  addMapConfigRoute(app, mergedOptions.vcm ? `${mergedOptions.vcm}/map.config.json` : null, mergedOptions.auth, mergedOptions.config, true);
+  addIndexRoute(app, server, true, mergedOptions.vcm, mergedOptions.auth);
   addPluginAssets(app, 'dist');
 
-  if (!options.vcm) {
+  if (!mergedOptions.vcm) {
     logger.spin('compiling preview');
     if (!fs.existsSync(resolveMapUi('plugins', 'node_modules'))) {
       logger.info('Could not detect node_modules in map ui plugins. Assuming map UI not setup');
@@ -98,12 +102,12 @@ export default async function preview(options) {
     logger.info('@vcmap/ui built for preview');
     app.use('/assets', express.static(path.join(getContext(), 'node_modules', '@vcmap', 'ui', 'dist', 'assets')));
     app.use('/plugins', express.static(path.join(getContext(), 'dist', 'plugins')));
-    await addConfigRoute(app, options.auth, options.config, true);
+    await addConfigRoute(app, mergedOptions.auth, mergedOptions.config, true);
   }
 
   app.use(server.middlewares);
 
-  const port = options.port || 5005;
+  const port = mergedOptions.port || 5005;
   await app.listen(port);
   logger.info(`Server running on port ${port}`);
 }

package/src/serve.js

@@ -15,10 +15,11 @@ import {
   resolveMapUi,
 } from './hostingHelpers.js';
 import { getPluginName } from './packageJsonHelpers.js';
+import { getVcmConfigJs } from './pluginCliHelper.js';
 
 /**
  * @typedef {HostingOptions} ServeOptions
- * @property {string} [mapConfig] - an filename or URL to a map config
+ * @property {string} [mapConfig] - a filename or URL to a map config
  */
 
 async function getProxy(protocol, port) {
@@ -48,6 +49,13 @@ async function getProxy(protocol, port) {
   if (hasThisPlugin) {
     delete proxy[hasThisPlugin];
   }
+
+  // exampleData is not part of the @vcmap/ui package and must be proxied therefore
+  proxy['^/exampleData'] = {
+    target: 'https://raw.githubusercontent.com/virtualcitySYSTEMS/map-ui/main',
+    changeOrigin: true,
+    secure: false,
+  };
   return proxy;
 }
 
@@ -60,13 +68,15 @@ export default async function serve(options) {
     logger.error('Can only serve in dev mode, if the map ui is a dependency of the current context');
     return;
   }
+  const { default: vcmConfigJs } = await getVcmConfigJs();
+  const mergedOptions = { ...vcmConfigJs, ...options };
   await printVcmapUiVersion();
   checkReservedDirectories();
   const app = express();
-  const port = options.port || 8008;
+  const port = mergedOptions.port || 8008;
 
   logger.info('Starting development server...');
-  const proxy = await getProxy(options.https ? 'https' : 'http', port);
+  const proxy = await getProxy(mergedOptions.https ? 'https' : 'http', port);
 
   const server = await createServer({
     root: getContext(),
@@ -90,9 +100,9 @@ export default async function serve(options) {
       createConfigJsonReloadPlugin(),
     ],
     server: {
-      middlewareMode: 'html',
-      https: options.https,
-      proxy,
+      middlewareMode: true,
+      https: mergedOptions.https,
+      proxy: { ...mergedOptions.proxy, ...proxy },
     },
     css: {
       preprocessorOptions: {
@@ -103,10 +113,10 @@ export default async function serve(options) {
     },
   });
 
-  addMapConfigRoute(app, options.mapConfig, options.auth, options.config);
+  addMapConfigRoute(app, mergedOptions.mapConfig, mergedOptions.auth, mergedOptions.config);
   addIndexRoute(app, server);
   addPluginAssets(app, 'src');
-  await addConfigRoute(app, options.auth, options.config);
+  await addConfigRoute(app, mergedOptions.auth, mergedOptions.config);
 
   app.use(server.middlewares);
 

package/src/update.js

@@ -0,0 +1,50 @@
+import { logger } from '@vcsuite/cli-logger';
+import { DepType, getPackageJson, installDeps } from './packageJsonHelpers.js';
+import { name, promiseExec } from './pluginCliHelper.js';
+
+/**
+ * Update peer dependencies of a provided packageJson with @vcmap/ui@latest peers
+ * @param {Object} pluginPeer - peerDependencies of a plugin
+ * @param {string} pluginPath
+ * @returns {Promise<void>}
+ */
+export async function updatePeerDependencies(pluginPeer, pluginPath) {
+  const { stdout, stderr } = await promiseExec('npm view @vcmap/ui --json');
+  logger.error(stderr);
+  const { name: mapName, peerDependencies: mapPeer } = JSON.parse(stdout);
+  const peerDeps = [`${mapName}@latest`]; // @vcmap/ui is a required peer dep and will be updated in any case
+  if (pluginPeer) {
+    const pluginPeerDeps = Object.keys(pluginPeer)
+      .filter(depName => !!mapPeer[depName] && pluginPeer[depName] !== mapPeer[depName])
+      .map(depName => `${depName}@${mapPeer[depName]}`);
+    peerDeps.push(pluginPeerDeps);
+  }
+  logger.spin('Updating peer dependencies');
+  await installDeps(peerDeps, DepType.PEER, pluginPath);
+  logger.stopSpinner();
+  logger.success('Updated peer dependencies');
+}
+
+/**
+ * Updates the @vcmap/plugin-cli
+ * @param {string} pluginPath
+ * @returns {Promise<void>}
+ */
+async function updateCli(pluginPath) {
+  logger.spin(`Updating ${name}`);
+  await installDeps([`${name}@latest`], DepType.DEV, pluginPath);
+  logger.stopSpinner();
+  logger.success(`Updated ${name}`);
+}
+
+/**
+ * Updating peer dependencies to @vmap/ui@latest
+ * Updating @vcmap/plugin-cli
+ * @returns {Promise<void>}
+ */
+export default async function update() {
+  const packageJson = await getPackageJson();
+  await updatePeerDependencies(packageJson.peerDependencies, process.cwd());
+  await updateCli(process.cwd());
+  logger.success(`Updated plugin ${packageJson.name}`);
+}

package/assets/helloWorld/build/staging/Dockerfile

@@ -1,2 +0,0 @@
-FROM httpd:2-buster
-COPY * /usr/local/apache2/htdocs/

package/assets/helloWorld/src/helloWorld.vue

@@ -1,54 +0,0 @@
-<template>
-  <v-sheet class="hello-world">
-    <v-card class="pa-2 ma-2">
-      <v-container>
-        <v-row class="justify-center mb-4">
-          <h1>{{ $t('helloWorld.helloWorld') }}</h1>
-        </v-row>
-        <v-row class="justify-center mb-4">
-          <v-img
-            :src="logoUrl"
-            alt="plugin-assets example"
-            max-width="200"
-          />
-        </v-row>
-        <v-row class="justify-center">
-          <VcsButton
-            icon="mdi-times"
-            @click="closeSelf"
-          >
-            {{ $t('helloWorld.close')}}
-          </VcsButton>
-        </v-row>
-      </v-container>
-    </v-card>
-  </v-sheet>
-</template>
-
-<style>
-.hello-world {
-  background-color: aqua;
-}
-</style>
-<script>
-  import { inject } from 'vue';
-  import { VcsButton, getPluginAssetUrl } from '@vcmap/ui';
-  import { name } from '../package.json';
-
-  export const windowId = 'hello_world_window_id_plugin-cli';
-
-  export default {
-    name: 'HelloWorld',
-    components: { VcsButton },
-    setup() {
-      const app = inject('vcsApp');
-
-      return {
-        closeSelf() {
-          app.windowManager.remove(windowId);
-        },
-        logoUrl: getPluginAssetUrl(app, name, 'plugin-assets/vcs_logo.png'),
-      };
-    },
-  };
-</script>

package/assets/helloWorld/src/index.js

@@ -1,72 +0,0 @@
-import { WindowSlot } from '@vcmap/ui';
-import { version, name } from '../package.json';
-import HelloWorld, { windowId } from './helloWorld.vue';
-
-/**
- * @param {T} config - the configuration of this plugin instance, passed in from the app.
- * @param {string} baseUrl - the absolute URL from which the plugin was loaded (without filename, ending on /)
- * @returns {import("@vcmap/ui/src/vcsUiApp").VcsPlugin<T>}
- * @template {Object} T
- * @template {Object} S
- */
-export default function(config, baseUrl) {
-  return {
-    get name() { return name; },
-    get version() { return version; },
-    /**
-     * @param {import("@vcmap/ui").VcsUiApp} vcsUiApp
-     * @param {S=} state
-     * @returns {Promise<void>}
-     */
-    initialize: async (vcsUiApp, state) => {
-      console.log('Called before loading the rest of the current context. Passed in the containing Vcs UI App ');
-    },
-    /**
-     * @param {import("@vcmap/ui").VcsUiApp} vcsUiApp
-     * @returns {Promise<void>}
-     */
-    onVcsAppMounted: async (vcsUiApp) => {
-      console.log('Called when the root UI component is mounted and managers are ready to accept components');
-      vcsUiApp.windowManager.add({
-        id: windowId,
-        component: HelloWorld,
-        WindowSlot: WindowSlot.DETACHED,
-        position: {
-          left: '40%',
-          right: '40%',
-        },
-      }, name);
-    },
-    /**
-     * @returns {Promise<S>}
-     */
-    getState: async () => {
-      console.log('Called when serializing this plugin instance');
-      return {};
-    },
-    /**
-     * @returns {Promise<T>}
-     */
-    toJSON: async () => {
-      console.log('Called when serializing this plugin instance');
-      return {};
-    },
-    i18n: {
-      en: {
-        helloWorld: {
-          helloWorld: '@vcmap/plugin-cli - Hello World',
-          close: 'Close',
-        },
-      },
-      de: {
-        helloWorld: {
-          helloWorld: '@vcmap/plugin-cli - Hallo Welt',
-          close: 'Schließen',
-        },
-      },
-    },
-    destroy() {
-      console.log('hook to cleanup');
-    },
-  };
-};