@vcmap/plugin-cli 2.0.10 → 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.10",
+  "version": "2.0.12",
   "description": "A CLI to help develop and build plugins for the VC Map",
   "main": "index.js",
   "type": "module",
@@ -26,7 +26,7 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@vcmap/rollup-plugin-vcs-ol": "^1.0.1",
+    "@vcmap/rollup-plugin-vcs-ol": "^1.0.2",
     "@vcsuite/cli-logger": "^1.0.0",
     "archiver": "^5.0.0",
     "commander": "^6.0.0",
@@ -34,14 +34,14 @@
     "prompts": "^2.4.1",
     "sass": "1.32.13",
     "semver": "^7.3.5",
-    "unplugin-vue-components": "^0.21.1",
-    "vite": "^2.9.14",
-    "vite-plugin-vue2": "^2.0.1",
-    "vue-template-compiler": "~2.7.3"
+    "tar": "^6.1.13",
+    "vite": "^3.2.0",
+    "vite-plugin-vue2": "^2.0.2",
+    "vue-template-compiler": "~2.7.14"
   },
   "peerDependencies": {
-    "@vcmap/ui": "^5.0.0-rc.11",
-    "vue": "~2.7.3"
+    "@vcmap/ui": "^5.0.0-rc.15",
+    "vue": "~2.7.14"
   },
   "peerDependenciesMeta": {
     "@vcmap/ui": {

package/src/build.js

@@ -3,8 +3,6 @@ import fs from 'fs/promises';
 import { createVuePlugin } from 'vite-plugin-vue2';
 import vcsOl from '@vcmap/rollup-plugin-vcs-ol';
 import { logger } from '@vcsuite/cli-logger';
-import { VuetifyResolver } from 'unplugin-vue-components/dist/resolvers.js';
-import Components from 'unplugin-vue-components/dist/vite.js';
 import { getPluginEntry, getPluginName } from './packageJsonHelpers.js';
 import { getContext } from './context.js';
 
@@ -21,14 +19,6 @@ export function getDefaultConfig() {
     publicDir: false,
     plugins: [
       createVuePlugin(),
-      Components({
-        resolvers: [
-          VuetifyResolver(),
-        ],
-        dirs: ['./src'],
-        include: [],
-        exclude: [],
-      }),
       vcsOl(),
     ],
   };

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');
 }